# Understanding the Directory Structure of Pumpkin-MC/Pumpkin: A Rust Workspace Guide

> Explore the Pumpkin-MC/Pumpkin Rust workspace directory structure. Discover its 10+ crates, including core logic, chunk systems, and packet management.

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

---

**The Pumpkin-MC/Pumpkin repository follows a Rust workspace architecture with 10+ specialized crates, where the `pumpkin/` crate contains core server logic, `pumpkin-world/` handles chunk systems, and `pumpkin-protocol/` manages Minecraft packet serialization.**

Pumpkin is a modular, high-performance Minecraft server implementation written in Rust. Understanding the directory structure of Pumpkin-MC/Pumpkin is essential for developers contributing to the codebase or building plugins. The repository uses Cargo workspaces to organize distinct subsystems—ranging from world generation to network protocol handling—into separate, maintainable crates.

## Workspace Organization at a Glance

The repository root contains a **Cargo.toml** workspace definition that coordinates multiple member crates. Each crate follows a consistent pattern with `src/` directories containing implementation code and individual [`Cargo.toml`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/Cargo.toml) files defining specific dependencies.

The top-level structure includes these primary components:

- **`pumpkin/`** – Core server engine (entity systems, world ticks, gameplay mechanics)
- **`pumpkin-world/`** – Low-level world data structures and chunk loading pipeline
- **`pumpkin-protocol/`** – Minecraft network protocol serialization and packet codecs
- **`pumpkin-plugin-api/`** – Public API for third-party plugin development
- **`pumpkin-nbt/`** – Named Binary Tag format handling for player and world data
- **`pumpkin-inventory/`** – Container abstractions, screen handlers, and slot management
- **`pumpkin-data/`** – Auto-generated constants for items, sounds, and status effects
- **`pumpkin-config/`** – Configuration structures parsed from YAML files
- **`pumpkin-codecs/`** – Generic serialization framework used across crates
- **`pumpkin-api-macros/`** – Procedural macros supporting the plugin API
- **`assets/`** – Static resource files including world event definitions

## Core Server Logic: The `pumpkin` Crate

The **`pumpkin`** crate serves as the main server executable, importing other workspace members as dependencies. Located at `pumpkin/src/`, this crate contains the primary `Server` struct and coordinates entity systems, world ticks, and player interactions.

Key implementation files include:

- [`pumpkin/src/world/mod.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin/src/world/mod.rs) – World mechanics including terrain, time, weather, and portals
- [`pumpkin/src/lib.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin/src/lib.rs) – Exports the main `Server` struct and core runtime

The server implementation relies on **tokio** for async runtime management, as evidenced by the initialization patterns found in the source.

## World Management with `pumpkin-world`

The **`pumpkin-world`** crate isolates low-level world representation from high-level gameplay logic. This separation allows efficient chunk management independent of entity simulation.

Critical files in this crate include:

- [`pumpkin-world/src/chunk_system/mod.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-world/src/chunk_system/mod.rs) – Implements the chunk loading pipeline and block storage
- `pumpkin-world/src/` – Contains dimension definitions and world info structures

The chunk system handles the complex lifecycle of Minecraft chunks, from generation to serialization, without coupling to the main server's tick loop.

## Protocol Implementation in `pumpkin-protocol`

Network communication flows through the **`pumpkin-protocol`** crate, which implements Minecraft's binary protocol. This crate manages packet serialization for both Java and Bedrock editions when supported.

Key components reside in:

- [`pumpkin-protocol/src/packet.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-protocol/src/packet.rs) – Core packet definitions and serialization logic
- [`pumpkin-protocol/src/lib.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-protocol/src/lib.rs) – Protocol-wide exports and codec utilities

The protocol layer translates between raw network bytes and Rust data structures, ensuring type-safe packet handling throughout the connection lifecycle.

## Plugin Development Architecture

### The `pumpkin-plugin-api` Crate

Third-party extensions integrate through the **`pumpkin-plugin-api`** crate. Located in `pumpkin-plugin-api/src/`, this crate defines the event system, permission hooks, and logging interfaces.

Representative files include:

- [`pumpkin-plugin-api/src/lib.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-plugin-api/src/lib.rs) – Main API surface with `Plugin` trait and `PluginContext`
- Event definitions allowing hooks into `PlayerJoinEvent` and other server events

Plugins implement the async `Plugin` trait and register event handlers through the context object.

### Supporting Macros: `pumpkin-api-macros`

The **`pumpkin-api-macros`** crate at [`pumpkin-api-macros/src/lib.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-api-macros/src/lib.rs) provides procedural macros that simplify plugin boilerplate. These macros generate glue code for event registration and command parsing at compile time.

## Data Serialization and Assets

### NBT Handling: `pumpkin-nbt`

The **`pumpkin-nbt`** crate manages Named Binary Tag format used for player inventories, level data, and entity storage. Implementation in [`pumpkin-nbt/src/lib.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-nbt/src/lib.rs) provides serialization and deserialization utilities compatible with Minecraft's NBT specification.

### Generated Game Data: `pumpkin-data`

The **`pumpkin-data`** crate contains auto-generated Rust code derived from vanilla Minecraft data tables. Files like [`pumpkin-data/src/generated/item_stack/mod.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-data/src/generated/item_stack/mod.rs) export constants for item IDs, sound identifiers, and status effect mappings, ensuring the server remains synchronized with client expectations.

### Serialization Framework: `pumpkin-codecs`

Underpinning many crates is the **`pumpkin-codecs`** library in [`pumpkin-codecs/src/codec/mod.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-codecs/src/codec/mod.rs). This generic framework provides primitive codecs and builders for maps and lists, standardizing how structured data moves between disk, network, and memory representations.

## Configuration and Inventory Systems

### Server Configuration: `pumpkin-config`

Server administrators modify behavior through YAML files parsed by the **`pumpkin-config`** crate. Located at `pumpkin-config/src/`, this crate defines structs for whitelist management, resource pack URLs, and server links. The [`server_links.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/server_links.rs) file specifically handles parsing of server metadata configurations.

### Inventory Management: `pumpkin-inventory`

Player and container inventories are abstracted by the **`pumpkin-inventory`** crate. The [`pumpkin-inventory/src/screen_handler.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-inventory/src/screen_handler.rs) file defines window properties and slot mappings, while [`pumpkin-inventory/src/lib.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-inventory/src/lib.rs) exposes inventory operations independent of the core game loop.

## Practical Code Examples

### Starting a Minimal Pumpkin Server

To initialize the server runtime, import the core `Server` struct and configuration types:

```rust
use pumpkin::server::Server;
use pumpkin_config::config::Config;

#[tokio::main]
async fn main() {
    // Load server config with sensible defaults
    let cfg = Config::load().await.unwrap();

    // Instantiate and run the server
    let server = Server::new(cfg).await.unwrap();
    server.run().await.unwrap();
}

```

This pattern references the `pumpkin::server::Server` implementation defined in the `pumpkin` crate's source.

### Registering a Plugin Event

Plugins hook into server lifecycle through the API crate:

```rust
use pumpkin_plugin_api::events::PlayerJoinEvent;
use pumpkin_plugin_api::plugin::{Plugin, PluginContext};

pub struct WelcomePlugin;

#[async_trait::async_trait]
impl Plugin for WelcomePlugin {
    async fn enable(&self, ctx: PluginContext) {
        ctx.register_event::<PlayerJoinEvent>(|event| async move {
            let player = event.player();
            player.send_message("Welcome to the Pumpkin server!").await;
        });
    }
}

```

The `PlayerJoinEvent` and `PluginContext` types are exported from [`pumpkin-plugin-api/src/lib.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-plugin-api/src/lib.rs).

### Reading NBT Data Files

Access player data or schematic files using the NBT utilities:

```rust
use pumpkin_nbt::tag::Tag;
use std::fs::File;
use std::io::BufReader;

fn read_player_nbt(path: &str) -> Tag {
    let file = File::open(path).unwrap();
    let mut reader = BufReader::new(file);
    pumpkin_nbt::deserializer::from_reader(&mut reader).unwrap()
}

```

This functionality is anchored in [`pumpkin-nbt/src/lib.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-nbt/src/lib.rs) according to the current source tree.

## Summary

- **Pumpkin-MC/Pumpkin** organizes code as a Rust workspace with specialized crates for each subsystem
- The **`pumpkin`** crate contains the main server executable and world tick logic in [`pumpkin/src/world/mod.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin/src/world/mod.rs)
- **World data** is isolated in `pumpkin-world/`, specifically [`pumpkin-world/src/chunk_system/mod.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-world/src/chunk_system/mod.rs) for chunk management
- **Network protocol** handling resides in [`pumpkin-protocol/src/packet.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-protocol/src/packet.rs)
- **Plugins** integrate via [`pumpkin-plugin-api/src/lib.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-plugin-api/src/lib.rs) using async traits and event registration
- **NBT serialization** utilities are available in [`pumpkin-nbt/src/lib.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-nbt/src/lib.rs) for data persistence
- **Generated game constants** live in `pumpkin-data/src/generated/` and update automatically from vanilla Minecraft definitions

## Frequently Asked Questions

### What is the main entry point for running a Pumpkin server?

The primary entry point is the `Server` struct defined in [`pumpkin/src/lib.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin/src/lib.rs) within the core `pumpkin` crate. This struct initializes the configuration system, opens network listeners, and starts the world tick loop. Runtime execution begins by calling `Server::new()` followed by `server.run()` in an async context.

### How does the Pumpkin codebase handle Minecraft protocol serialization?

Packet serialization is implemented in the `pumpkin-protocol` crate, specifically within [`pumpkin-protocol/src/packet.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-protocol/src/packet.rs) and related codec files. This crate translates between Rust data structures and Minecraft's binary wire format, supporting the protocol versions the server targets. The separation into its own crate allows protocol changes without modifying core game logic.

### Where are world chunks stored and managed in the Pumpkin repository?

Chunk data structures and loading pipelines are defined in [`pumpkin-world/src/chunk_system/mod.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-world/src/chunk_system/mod.rs) and supporting files under `pumpkin-world/src/`. This crate handles the low-level block storage, dimension definitions, and chunk I/O operations, while the `pumpkin` crate coordinates higher-level world mechanics like weather and time.

### How do I create a plugin for Pumpkin-MC/Pumpkin?

Develop plugins by implementing the `Plugin` trait from [`pumpkin-plugin-api/src/lib.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-plugin-api/src/lib.rs). Your plugin must provide an `enable` method that receives a `PluginContext`, through which you register event handlers like `PlayerJoinEvent`. The `pumpkin-api-macros` crate provides procedural macros to reduce boilerplate when defining commands and event listeners.