# Main Modules and Components of the Pumpkin-MC/Pumpkin Minecraft Server

> Explore the core modules of the Pumpkin Minecraft server: pumpkin-config, pumpkin-protocol, pumpkin-world, pumpkin-plugin-api, and pumpkin-data. Understand its architecture for networking, world management, and plugins.

- Repository: [Pumpkin MC/Pumpkin](https://github.com/Pumpkin-MC/Pumpkin)
- Tags: deep-dive
- Published: 2026-07-23

---

**Pumpkin-MC/Pumpkin is organized into a collection of specialized Rust crates including pumpkin-config, pumpkin-protocol, pumpkin-world, pumpkin-plugin-api, and pumpkin-data, each handling distinct subsystems like networking, world management, and plugin extensibility.**

The Pumpkin-MC/Pumpkin project is a high-performance Minecraft server implementation written entirely in Rust. Understanding the main modules and components of Pumpkin-MC/Pumpkin is essential for developers looking to extend the server, write plugins, or contribute to the core codebase. The architecture follows a modular crate-based design where each subsystem is isolated into its own library with clear public APIs exported through the top-level `pumpkin` crate.

## Core Configuration and Protocol Stack

### Configuration Management

The **pumpkin-config** crate handles all server configuration through typed TOML files. It defines `BasicConfiguration` and `AdvancedConfiguration` structs and implements the `LoadConfiguration` trait for validation. Configuration loading is the first step at runtime, supplying options to the rest of the system via `PumpkinConfig::load` as defined in [`pumpkin-config/src/lib.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-config/src/lib.rs).

### Network Protocol Handling

**pumpkin-protocol** manages network communication for both Java and Bedrock editions. It spawns TCP listeners for Java clients and UDP sockets for Bedrock clients, wrapping connections in `JavaClient` or `BedrockClient` objects. The crate exposes modules for `net::java`, `net::bedrock`, `query`, `rcon`, and `lan_broadcast` as listed in [`pumpkin-protocol/src/lib.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-protocol/src/lib.rs).

### Data Serialization

Low-level serialization lives in **pumpkin-codecs** and **pumpkin-nbt**. The codecs crate handles var-int, UUID, string, and other binary formats used by the protocol layer, exposing `struct_builder`, `number`, `list_builder`, and `map_like` modules. **pumpkin-nbt** specifically manages the Named Binary Tag format used by Minecraft, providing `tag`, `serializer`, `deserializer`, and `compound` functionality in [`pumpkin-nbt/src/lib.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-nbt/src/lib.rs).

## World Management and Game Data

### World Engine

The **pumpkin-world** crate contains the core world implementation including chunk loading, saving, lighting calculations, and world generation. The primary entry point is [`pumpkin-world/src/world.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-world/src/world.rs), which exports `world`, `chunk`, and `lighting` modules. This crate manages entity placement and coordinates with the top-level server to run the main tick loop.

### Static Game Definitions

**pumpkin-data** stores static definitions for blocks, items, biomes, and advancements generated from official Minecraft data files. **pumpkin-codegen** produces the data structures used at runtime, including `world_event`, `item`, `recipe`, and `sound` definitions. These crates ensure type-safe access to game constants as implemented in [`pumpkin-data/src/lib.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-data/src/lib.rs) and [`pumpkin-codegen/src/lib.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-codegen/src/lib.rs).

### Inventory System

Player and container inventories are handled by **pumpkin-inventory**, which manages item stacking logic and container types. The crate exposes `inventory` and `container` modules from [`pumpkin-inventory/src/lib.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-inventory/src/lib.rs), providing the backing storage for player inventories and chest-like blocks.

## Plugin Architecture and Utilities

### Plugin API

**pumpkin-plugin-api** defines the public interface for extending the server. It provides an event system with events like `ServerLoadEvent` and `ServerCommandEvent`, a task scheduler, and permission handlers. The crate exports `plugin`, `server`, and `forms` modules from [`pumpkin-plugin-api/src/lib.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-plugin-api/src/lib.rs), allowing third-party code to register commands and listen for lifecycle events.

### Utility Functions

**pumpkin-util** provides cross-cutting concerns including UUID helpers, world seed generation, text component formatting, and permission level management. Located in [`pumpkin-util/src/lib.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-util/src/lib.rs), it exposes `world_seed`, `uuid`, `text`, `permission`, and `registry` modules used throughout the codebase.

### Macros and Code Generation

**pumpkin-macros** and **pumpkin-api-macros** supply procedural macros that reduce boilerplate, such as the `send_cancellable!` macro. These crates simplify repetitive patterns across the protocol and plugin layers as defined in [`pumpkin-macros/src/lib.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-macros/src/lib.rs).

## Server Orchestration and Runtime

### Top-Level Server Crate

The **pumpkin** crate itself orchestrates all subsystems and provides the server entry point. It instantiates `PumpkinServer`, initializes logging via `init_logger`, and loads vanilla data through `VanillaData::load()`. The crate re-exports internal modules including `block`, `command`, `crash`, `data`, `entity`, `error`, `item`, `logging`, `net`, `plugin`, `server`, and `world` from [`pumpkin/src/lib.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin/src/lib.rs).

The following example demonstrates server initialization from a binary crate:

```rust
use pumpkin::PumpkinServer;
use pumpkin_config::PumpkinConfig;

#[tokio::main]
async fn main() {
    // Load configuration from the default `pumpkin.toml`
    let cfg = PumpkinConfig::load(std::path::Path::new("."));
    // Initialise the logger based on the advanced config
    pumpkin::init_logger(&cfg.advanced);
    // Load the vanilla data (blocks, items, etc.)
    let vanilla = pumpkin::data::VanillaData::load().await;
    // Build the server
    let server = PumpkinServer::new(cfg.basic, cfg.advanced, vanilla).await;
    // Optionally load plugins
    server.init_plugins().await;
    // Run the main loop (accepts connections, ticks world, etc.)
    server.start().await;
}

```

### Plugin Development Example

Developers interact with the server through the **pumpkin-plugin-api** crate. The following shows registering a simple command:

```rust
use pumpkin_plugin_api::plugin::{Plugin, PluginContext};
use pumpkin_plugin_api::command::CommandSender;

pub struct HelloPlugin;

#[plugin::async_trait]
impl Plugin for HelloPlugin {
    async fn on_load(&self, ctx: PluginContext) {
        // Register a `/hello` command that replies with “Hello, world!”
        ctx.register_command("hello", |sender, _args| async move {
            sender
                .send_message("Hello, world!".into())
                .await
                .ok();
        })
        .await;
    }
}

```

## Summary

- **Pumpkin-MC/Pumpkin** is divided into roughly a dozen specialized Rust crates, each encapsulating a specific subsystem.
- **pumpkin-config**, **pumpkin-protocol**, and **pumpkin-codecs** handle configuration, networking, and binary serialization respectively.
- **pumpkin-world**, **pumpkin-data**, and **pumpkin-inventory** manage game state, static definitions, and player items.
- **pumpkin-plugin-api** and **pumpkin-util** provide extension points and common helpers for developers.
- The top-level **pumpkin** crate orchestrates all components via `PumpkinServer` and exposes the public API modules.

## Frequently Asked Questions

### What is the difference between pumpkin-data and pumpkin-codegen?

**pumpkin-data** contains the actual static game definitions like block and item IDs, while **pumpkin-codegen** is the build-time crate that generates the Rust data structures used by other components. Codegen processes official Minecraft data files to produce typed constants for world events, recipes, and sounds as referenced in [`pumpkin-codegen/src/lib.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-codegen/src/lib.rs).

### How does Pumpkin-MC/Pumpkin support both Java and Bedrock editions?

The **pumpkin-protocol** crate implements dual stack networking, spawning TCP listeners for Java Edition clients and UDP sockets for Bedrock Edition clients. Each connection type is wrapped in protocol-specific client objects (`JavaClient` or `BedrockClient`) that share common serialization logic from **pumpkin-codecs** and **pumpkin-nbt**.

### Where is the server entry point defined in Pumpkin-MC/Pumpkin?

The server entry point and main orchestration logic reside in the top-level **pumpkin** crate, specifically within [`pumpkin/src/lib.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin/src/lib.rs). This file defines the `PumpkinServer` struct, the `init_logger` function, and the module re-exports that form the public API for server initialization and plugin development.

### Can developers write plugins for Pumpkin-MC/Pumpkin?

Yes, developers can write plugins using the **pumpkin-plugin-api** crate, which provides an event system, command registration, and scheduler. Plugins implement the `Plugin` trait and can listen for events like `ServerLoadEvent` as demonstrated in the plugin development example above.