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

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. 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:

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 provides schedule_delayed_task:

// 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 handles chunk management, lighting, and entity tracking. For structure generation, the template system in pumpkin-world/src/generation/structure/template/mod.rs allows loading and placing vanilla structures.

To load and place a structure template:

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.

Configuration and Server State Management

Server settings utilize TOML configuration handled by the pumpkin-config crate. In pumpkin-config/src/world.rs, the WorldConfig struct defines world-specific parameters like seed and spawn location.

Reading configuration files:

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 and pumpkin/src/world/weather.rs, you can query current server tick count and meteorological conditions:

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. This structure separates subsystems into discrete crates:

• pumpkin (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): NBT parsing and serialization for save files.
• pumpkin-config (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.

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 and pumpkin-world/src/world.rs.
• Code examples in pumpkin-plugin-api/src/scheduler.rs and pumpkin-world/src/generation/structure/template/mod.rs demonstrate plugin scheduling and world manipulation.
• Workspace definition in 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 and 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 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 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.

Which crate handles NBT serialization for world saves?

The pumpkin-nbt crate, specifically 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}