# Developer Documentation for Pumpkin-MC/Pumpkin: A Complete Guide to the Rust Minecraft Server

> Explore the comprehensive developer documentation for the Pumpkin Rust Minecraft server. Discover README concepts, module docs, API references, and contribution guides to get started.

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

---

**Pumpkin provides a layered documentation ecosystem spanning high-level concepts in README.md, architectural module docs in Rust source files, auto-generated API references via cargo doc, and contribution guidelines in CONTRIBUTING.md.**

Pumpkin is a Rust-based Minecraft server implementation designed for performance, security, and extensibility. The project maintains comprehensive developer documentation that covers everything from quick-start deployment guides to in-depth WebAssembly plugin APIs. Whether you are contributing core infrastructure or building server modifications, you will find authoritative resources both in the repository and at the official pumpkinmc.org site.

## Project Overview and Quick-Start Resources

The primary entry point for developers is the **README.md**, which explains the server’s purpose, performance goals, Vanilla compatibility promises, and current development status. For step-by-step instructions on building the server from source and connecting your first client, the **Quick Start** section in that same file provides terminal commands and configuration basics.

The **official documentation site** at pumpkinmc.org aggregates generated API references, server configuration options, and runtime command guides. This site is built directly from the repository source, ensuring it remains synchronized with the latest `master` branch.

## Contribution Guidelines and Community Standards

Before submitting patches, developers must review **CONTRIBUTING.md**, which defines the bug report format, feature request procedures, and pull request requirements. The file outlines continuous integration expectations, code style rules, and the review process enforced by maintainers.

Community interaction is governed by **CODE_OF_CONDUCT.md**, while security vulnerabilities are covered under **SECURITY.md**, which provides a responsible disclosure policy. Real-time discussion, architecture debates, and support occur on the project’s Discord server, accessible via the invite link in the repository.

## API Documentation and Source Code References

Pumpkin leverages Rust’s built-in documentation system. Running `cargo doc` generates browsable HTML references for every public crate, populated by extensive `//!` module-level comments and `///` doc comments in the source.

### Plugin Development and Scheduler API

The **Plugin API** is exposed through the `pumpkin-plugin-api` crate, specifically in [`pumpkin-plugin-api/src/lib.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-plugin-api/src/lib.rs). This module defines the `Plugin` trait, the `Context` struct for server interaction, and the `register_plugin!` macro required for WebAssembly entry points.

To create a minimal plugin that schedules recurring tasks:

```rust
use pumpkin_plugin_api::{
    Plugin, PluginMetadata, Context, register_plugin,
    permissions::PermissionLevel,
};

struct HelloWorld;

impl Plugin for HelloWorld {
    fn new() -> Self { HelloWorld }

    fn metadata(&self) -> PluginMetadata {
        PluginMetadata {
            name: "hello-world".into(),
            version: "0.1.0".into(),
            authors: vec!["YourName".into()],
            description: Some("Prints a message each tick".into()),
        }
    }

    fn on_load(&mut self, ctx: &mut Context) {
        // Schedule a recurring task that runs every 20 ticks (≈1 sec)
        ctx.schedule_repeating_task(20, |server| {
            server.log("Hello from Pumpkin plugin!");
        });
    }

    fn required_permission(&self) -> PermissionLevel {
        PermissionLevel::User
    }
}

// Register the plugin entry point (required macro)
register_plugin!(HelloWorld);

```

For delayed execution, the scheduler API in [`pumpkin-plugin-api/src/scheduler.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-plugin-api/src/scheduler.rs) provides `schedule_delayed_task`:

```rust
// Inside any server-side context (e.g., a command handler)
ctx.schedule_delayed_task(100, |server| {
    server.broadcast_chat("A minute has passed!");
});

```

### World Generation and Structure Templates

The `pumpkin-world` crate in [`pumpkin-world/src/world.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-world/src/world.rs) handles chunk management, lighting, and entity tracking. For structure generation, the template system in [`pumpkin-world/src/generation/structure/template/mod.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-world/src/generation/structure/template/mod.rs) allows loading and placing vanilla structures.

To load and place a structure template:

```rust
use pumpkin_world::generation::structure::template::{TemplateCache, TemplatePiece};
use pumpkin_data::Rotation;

let template = TemplateCache::get("igloo/top")
    .expect("Igloo template missing");

// Place the template at position (100, 64, 100) with no rotation/mirroring
let piece = TemplatePiece::new(template, Rotation::None, false, (100, 64, 100).into());

// Insert the piece into the world (requires a mutable world reference)
world.insert_structure_piece(piece);

```

The underlying cache implementation resides in [`pumpkin-world/src/generation/structure/template/cache.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-world/src/generation/structure/template/cache.rs).

### Configuration and Server State Management

Server settings utilize TOML configuration handled by the `pumpkin-config` crate. In [`pumpkin-config/src/world.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-config/src/world.rs), the `WorldConfig` struct defines world-specific parameters like seed and spawn location.

Reading configuration files:

```rust
use pumpkin_config::world::WorldConfig;

let cfg = WorldConfig::load("config/world.toml")
    .expect("Failed to read world config");
println!("World seed: {}", cfg.seed);

```

Accessing runtime world state such as time and weather is demonstrated in the core server crate. In [`pumpkin/src/world/time.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin/src/world/time.rs) and [`pumpkin/src/world/weather.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin/src/world/weather.rs), you can query current server tick count and meteorological conditions:

```rust
let time = world.time().ticks();          // Current tick count
let weather = world.weather();            // Weather state (clear, rain, thunder)
println!("Time: {}, Weather: {:?}", time, weather);

```

## Workspace Architecture and Module Organization

Pumpkin organizes code as a **Cargo workspace** defined in the root [`Cargo.toml`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/Cargo.toml). This structure separates subsystems into discrete crates:

- **`pumpkin`** ([`pumpkin/src/main.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin/src/main.rs)): Core server loop, networking, and glue code.
- **`pumpkin-world`**: World representation, chunk handling, lighting, and physics.
- **`pumpkin-nbt`** ([`pumpkin-nbt/src/lib.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-nbt/src/lib.rs)): NBT parsing and serialization for save files.
- **`pumpkin-config`** ([`pumpkin-config/src/lib.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-config/src/lib.rs)): Configuration parsing and server-level settings.
- **`pumpkin-plugin-api`**: Public API for WebAssembly plugins.
- **`pumpkin-inventory`**: Inventory UI and screen handlers.
- **`pumpkin-codecs`**: Low-level packet codecs for Java and Bedrock editions.
- **`pumpkin-util`**: Miscellaneous utilities such as JWT verification for Bedrock authentication in [`pumpkin-util/src/jwt/mod.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-util/src/jwt/mod.rs).

## Asset Files and Game Data

The `assets/` directory at the repository root contains JSON and NBT files that mirror vanilla Minecraft data, including block definitions, item properties, biomes, and structure templates. Plugin developers reference these assets when implementing features that must align with Vanilla game data.

## Summary

- **README.md** and **pumpkinmc.org** provide high-level goals, quick-start instructions, and browsable configuration references.
- **CONTRIBUTING.md**, **CODE_OF_CONDUCT.md**, and **SECURITY.md** define contribution workflows and community standards.
- **Rust Doc comments** throughout the workspace generate searchable API documentation via `cargo doc`, with critical entry points in [`pumpkin-plugin-api/src/lib.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-plugin-api/src/lib.rs) and [`pumpkin-world/src/world.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-world/src/world.rs).
- **Code examples** in [`pumpkin-plugin-api/src/scheduler.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-plugin-api/src/scheduler.rs) and [`pumpkin-world/src/generation/structure/template/mod.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-world/src/generation/structure/template/mod.rs) demonstrate plugin scheduling and world manipulation.
- **Workspace definition** in [`Cargo.toml`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/Cargo.toml) clarifies crate responsibilities, from NBT handling in `pumpkin-nbt` to configuration in `pumpkin-config`.

## Frequently Asked Questions

### How do I generate the API documentation locally for Pumpkin?

Run `cargo doc --open` from the repository root. This command builds HTML documentation for all workspace crates based on the `//!` module comments and `///` function documentation distributed throughout the source, particularly in [`pumpkin-plugin-api/src/lib.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-plugin-api/src/lib.rs) and [`pumpkin-world/src/world.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-world/src/world.rs).

### What is the entry point for developing a WebAssembly plugin for Pumpkin?

Implement the `Plugin` trait defined in [`pumpkin-plugin-api/src/lib.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-plugin-api/src/lib.rs) and invoke the `register_plugin!` macro to expose the entry point. The plugin must be compiled to WebAssembly and loaded by the server at runtime, utilizing the scheduler API in [`pumpkin-plugin-api/src/scheduler.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-plugin-api/src/scheduler.rs) for delayed or repeating tasks.

### Where are vanilla Minecraft assets stored in the Pumpkin repository?

Game data assets, including structure templates, block definitions, and biome configurations, reside in the `assets/` directory. These JSON and NBT files are essential for plugin developers who need to reference vanilla data or implement custom generation algorithms using the template system in [`pumpkin-world/src/generation/structure/template/mod.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-world/src/generation/structure/template/mod.rs).

### Which crate handles NBT serialization for world saves?

The `pumpkin-nbt` crate, specifically [`pumpkin-nbt/src/lib.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-nbt/src/lib.rs), manages Named Binary Tag parsing and serialization. This crate is critical for reading saved player data, structure templates, and chunk information from disk.