How to Integrate with Pumpkin-MC/Pumpkin APIs: A Complete Guide for Rust Developers

Integrating with Pumpkin-MC/Pumpkin APIs requires opening a TCP connection to the Rust-based Minecraft server and utilizing the Serializer and Deserializer helpers from the pumpkin-protocol crate to exchange packets, or leveraging the high-level query and rcon modules for status checks and remote command execution.

Pumpkin is a fully-Rust Minecraft server implementation that exposes its functionality through a modular crate architecture. Understanding how to integrate with Pumpkin-MC/Pumpkin APIs enables developers to build custom clients, administrative tools, and plugins that interact directly with the server's protocol layer without external binaries.

Understanding the Pumpkin API Architecture

Pumpkin organizes its functionality into distinct layers, each exposed as a separate crate. The public API surface resides primarily in the protocol and world crates:

• Protocol Layer (pumpkin-protocol): Handles network handshakes, packet (de)serialization, and Minecraft protocol implementations for both Java and Bedrock editions. Key files include pumpkin-protocol/src/packet.rs for packet definitions and pumpkin-protocol/src/serial/serializer.rs for wire-format encoding.
• World Layer (pumpkin-world): Manages chunk loading, entity states, block updates, and world persistence through pumpkin-world/src/world.rs and Anvil format support in pumpkin-world/src/world_info/anvil.rs.
• Configuration Layer (pumpkin-config): Parses TOML configuration files including server links, whitelists, and player data via pumpkin-config/src/server_links.rs and pumpkin-config/src/player_data.rs.
• Query Layer (pumpkin-protocol/src/query.rs): Implements legacy Server List Ping and RCON protocols for remote administration and server discovery.
• Codecs Layer (pumpkin-codecs): Provides NBT and JSON serialization utilities used throughout the server, defined in pumpkin-codecs/src/lib.rs.

Integration Method 1: Server Status Queries

For simple server monitoring or lobby browsers, use the Query API implemented in pumpkin-protocol/src/query.rs. This method requires no authentication and returns the MOTD, player counts, and version information using the classic Server List Ping protocol.

use pumpkin_protocol::query::status;

fn check_server_status() -> std::io::Result<()> {
    let server_status = status::get_status("127.0.0.1:25565")?;
    println!("MOTD: {}", server_status.description);
    println!("Players: {}/{}", server_status.players.online, server_status.players.max);
    Ok(())
}

Integration Method 2: Remote Command Execution (RCON)

Administrative tools can execute server commands remotely using the RCON protocol defined in pumpkin-protocol/src/query.rs. This requires enabling RCON in the server's TOML configuration and providing the configured password.

use pumpkin_protocol::query::rcon;

fn execute_remote_command() -> std::io::Result<()> {
    let response = rcon::execute(
        "127.0.0.1:25575",
        "my_rcon_password",
        "list"
    )?;
    println!("RCON response: {}", response);
    Ok(())
}

Integration Method 3: Full Protocol Handshake

For custom clients or bots that need to join the world and interact with entities, implement the full Minecraft protocol handshake using the packet system defined in pumpkin-protocol/src/packet.rs.

Step 1: Establish TCP Connection

Connect to the server's configured port. The default is 25565 for Java Edition and 19132 for Bedrock Edition, as defined in the configuration structures parsed by pumpkin-config/src/server_links.rs.

Step 2: Serialize the Handshake Packet

Use the Serializer from pumpkin-protocol/src/serial/serializer.rs to encode the initial handshake. This helper automatically handles var-int encoding, compression, and encryption once enabled.

use std::net::TcpStream;
use pumpkin_protocol::packet::Handshake;
use pumpkin_protocol::serial::Serializer;

let mut stream = TcpStream::connect("127.0.0.1:25565")?;
let handshake = Handshake {
    protocol_version: 761, // Minecraft 1.19.4
    server_address: "127.0.0.1".into(),
    server_port: 25565,
    next_state: 2, // 2 = login state
};
let mut serializer = Serializer::new(&mut stream);
serializer.write_packet(&handshake)?;

Step 3: Complete the Login Sequence

Send the LoginStart packet to initiate the login phase. In pumpkin-protocol/src/packet.rs, this struct handles the username and optional authentication data.

use pumpkin_protocol::packet::LoginStart;

let login = LoginStart {
    name: "my_bot".into(),
    ..Default::default()
};
serializer.write_packet(&login)?;

Step 4: Exchange Game Packets

Once authenticated, use the Deserializer from pumpkin-protocol/src/serial/deserializer.rs to read incoming packets and the Serializer to send responses such as chat messages.

use pumpkin_protocol::packet::ChatMessage;

let chat = ChatMessage {
    message: "{\"text\":\"Hello from Pumpkin API!\"}".into(),
    position: 0,
    sender: None,
};
serializer.write_packet(&chat)?;

Subscribing to World Events

Plugins and integrations can react to server state changes by subscribing to the WorldEvent enum defined in pumpkin-world/src/world_info/mod.rs. This allows your code to respond to chunk loads, entity spawns, and block updates through the world management system in pumpkin-world/src/world.rs rather than polling the server.

Key Source Files for API Integration

When building integrations, reference these critical source locations according to the Pumpkin-MC/Pumpkin source code:

• pumpkin-protocol/src/packet.rs: Central registry of all packet structs including Handshake, LoginStart, and ChatMessage.
• pumpkin-protocol/src/serial/serializer.rs: Handles var-int encoding, compression, and encryption for outgoing data streams.
• pumpkin-protocol/src/serial/deserializer.rs: Reconstructs Rust structs from incoming TCP byte streams.
• pumpkin-protocol/src/query.rs: Contains status::get_status and rcon::execute for lightweight integrations.
• pumpkin-config/src/server_links.rs: Defines configuration structures for RCON passwords, server ports, and metadata.
• pumpkin-world/src/world.rs: Core world management API exposing chunks, entities, and lighting data.

Summary

• Pumpkin-MC/Pumpkin APIs are exposed through Rust crates with the primary interface residing in pumpkin-protocol.
• Three integration tiers exist: status queries (no authentication), RCON commands (password-based), and full protocol handshake (game client simulation).
• Serialization is managed by Serializer and Deserializer helpers that automatically handle var-int encoding, compression, and encryption during the handshake.
• Default networking ports are 25565 for Java Edition gameplay and 25575 for RCON administration, configurable via pumpkin-config.
• World events can be captured through the WorldEvent enum in pumpkin-world for reactive plugin development.

Frequently Asked Questions

What is the default port for Pumpkin API connections?

The Java Edition protocol listens on port 25565 by default, while the RCON administrative interface typically uses port 25575. Bedrock Edition support utilizes port 19132. These values are parsed from TOML configuration files handled by pumpkin-config/src/server_links.rs.

Does Pumpkin support both Java and Bedrock protocol integration?

Yes. The Protocol layer in pumpkin-protocol handles packet formats for both Java and Bedrock editions. The serialization helpers in pumpkin-protocol/src/serial/serializer.rs and deserializer.rs automatically manage the wire-format differences between editions, allowing integrations to work with either protocol version.

How does Pumpkin handle packet encryption and compression?

The Serializer and Deserializer structs in pumpkin-protocol/src/serial/ automatically handle var-int encoding, compression, and encryption once the handshake completes. Your integration code interacts with high-level packet structs while the serializers manage the low-level byte manipulation and protocol state transitions.

Can I integrate with Pumpkin using languages other than Rust?

While Pumpkin exposes its APIs primarily as Rust crates, you can integrate from other languages by implementing the raw Minecraft protocol directly against the TCP socket using the packet formats defined in pumpkin-protocol/src/packet.rs, or by creating a Rust-based FFI bridge that wraps the Serializer and Deserializer helpers.

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