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

> Learn to integrate with Pumpkin-MC/Pumpkin APIs using Rust. Connect via TCP, send packets with Serializer/Deserializer, or use query/rcon for status and commands.

- Repository: [Pumpkin MC/Pumpkin](https://github.com/Pumpkin-MC/Pumpkin)
- Tags: how-to-guide
- Published: 2026-07-23

---

**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`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-protocol/src/packet.rs) for packet definitions and [`pumpkin-protocol/src/serial/serializer.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/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`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-world/src/world.rs) and Anvil format support in [`pumpkin-world/src/world_info/anvil.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/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`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-config/src/server_links.rs) and [`pumpkin-config/src/player_data.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-config/src/player_data.rs).
- **Query Layer** ([`pumpkin-protocol/src/query.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/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`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/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`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/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.

```rust
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`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-protocol/src/query.rs). This requires enabling RCON in the server's TOML configuration and providing the configured password.

```rust
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`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/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`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-config/src/server_links.rs).

### Step 2: Serialize the Handshake Packet

Use the `Serializer` from [`pumpkin-protocol/src/serial/serializer.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-protocol/src/serial/serializer.rs) to encode the initial handshake. This helper automatically handles var-int encoding, compression, and encryption once enabled.

```rust
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`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-protocol/src/packet.rs), this struct handles the username and optional authentication data.

```rust
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`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-protocol/src/serial/deserializer.rs) to read incoming packets and the `Serializer` to send responses such as chat messages.

```rust
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`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/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`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/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`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-protocol/src/packet.rs)**: Central registry of all packet structs including `Handshake`, `LoginStart`, and `ChatMessage`.
- **[`pumpkin-protocol/src/serial/serializer.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-protocol/src/serial/serializer.rs)**: Handles var-int encoding, compression, and encryption for outgoing data streams.
- **[`pumpkin-protocol/src/serial/deserializer.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-protocol/src/serial/deserializer.rs)**: Reconstructs Rust structs from incoming TCP byte streams.
- **[`pumpkin-protocol/src/query.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-protocol/src/query.rs)**: Contains `status::get_status` and `rcon::execute` for lightweight integrations.
- **[`pumpkin-config/src/server_links.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-config/src/server_links.rs)**: Defines configuration structures for RCON passwords, server ports, and metadata.
- **[`pumpkin-world/src/world.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/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`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/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`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-protocol/src/serial/serializer.rs) and [`deserializer.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/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`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/pumpkin-protocol/src/packet.rs), or by creating a Rust-based FFI bridge that wraps the `Serializer` and `Deserializer` helpers.