Pumpkin Architecture & Crates

Pumpkin is organized as a modular Cargo workspace composed of specialized crates. Each crate has distinct responsibilities, strictly defined boundaries, and minimal cross-dependencies.

This architecture enables high parallel compilation speeds, isolated testing, zero-cost data sharing, and clean separation between network protocols, game logic, and world management.

---

Workspace Crate Overview

Workspace Architecture at a Glance

Layer	Crates	Responsibilities
Core Runtime	pumpkin	Game loop, world ticking, player sessions, entity management, and event loops
Networking & Protocols	pumpkin-protocol, pumpkin-auth, pumpkin-nbt	Java/Bedrock packet serialization, Yggdrasil & Xbox Live authentication, SNBT
World & Gameplay	pumpkin-world, pumpkin-inventory, pumpkin-command	Region I/O (Anvil/Linear), terrain generation, block ticking, containers, Brigadier tree
Extensibility	pumpkin-plugin-runtime, pumpkin-host-bindings, pumpkin-plugin-api, pumpkin-plugin-wit	WebAssembly plugin execution via Wasmtime, WIT host APIs, native and WASM loaders
Foundations	pumpkin-data, pumpkin-config, pumpkin-util	Code-generated registries, typed configuration files, mathematical vectors, permissions

---

Detailed Crate Breakdown

1. pumpkin (Core Server)

• Path: crates/pumpkin
• Purpose: The main server binary and centralized orchestration engine.
• Responsibilities:
  • Initializes configuration, logging (tracing), and telemetry.
  • Spawns Tokio network listeners for Minecraft: Java Edition, Bedrock Edition, RCON, Query, and LAN broadcast.
  • Manages the server tick loop (Server::tick), coordinating world updates, player actions, entity movements, and chunk broadcasting.
  • Dispatches incoming client packets through crates/pumpkin/src/net/java/ and net/bedrock/.
  • Integrates the plugin manager, firing event handlers before and after packet processing.

2. pumpkin-protocol (Network Protocol)

• Path: crates/pumpkin-protocol
• Purpose: High-speed network wire format serialization and deserialization for Minecraft Java and Bedrock editions.
• Responsibilities:
  • Implements the ClientPacket (serialization) and ServerPacket (deserialization) traits.
  • Handles protocol primitives: VarInt, VarLong, UUIDs, NBT compounds, and string codecs.
  • Implements packets across all states: Handshake, Status, Login, Config, and Play.
  • Provides packet compression (ZLib/Fast compression) and packet encryption (AES-128/CFB8).
  • Encapsulates RCON and GameSpy4 Query protocols.

3. pumpkin-world (World & Chunks)

• Path: crates/pumpkin-world
• Purpose: World loading, saving, terrain generation, and chunk management.
• Responsibilities:
  • Supports multiple chunk storage formats:
    • Vanilla Anvil (.mca): Reading and writing standard region files.
    • Linear (.linear): High-efficiency zstd-compressed region format saving 50–95% disk space.
    • Slime (.slime): Single-file world format.
    • Pump: Native Pumpkin chunk storage format.
  • Implements world generation pipelines: Perlin noise heightmaps, 3D noise routers, biome climate parameters, placed features, carvers, and superflat terrain.
  • Manages block lighting and sky lighting propagation.
  • Coordinates chunk loading, unloading, and streaming via cylindrical chunk iterators.

4. pumpkin-data (Minecraft Datasets & Registries)

• Path: crates/pumpkin-data
• Purpose: Compile-time static registries and data tables generated directly from vanilla Minecraft assets and reports.
• Responsibilities:
  • Contains complete ID mappings, properties, and definitions for blocks, items, biomes, entities, sounds, particles, enchantments, and recipes.
  • Packet ID lookups across multiple Minecraft protocol versions.
  • Zero-cost lookup tables generated by tools/pumpkin-codegen.

5. pumpkin-config (Configuration Management)

• Path: crates/pumpkin-config
• Purpose: TOML configuration parsing, serialization, and validation.
• Responsibilities:
  • Loads and writes pumpkin.toml.
  • Configures server ports, compression thresholds, proxy modes, resource packs, logging levels, world settings, and Bedrock integration.
  • Provides safe defaults and schema validations.

6. pumpkin-inventory (Inventory & Containers)

• Path: crates/pumpkin-inventory
• Purpose: Server-side container window handlers and inventory mechanics.
• Responsibilities:
  • Manages player inventory, chest containers, crafting tables, furnaces, and villager trading screens.
  • Validates client slot clicks, drag operations, item stacking, and item splitting.
  • Coordinates window packet synchronization to ensure client inventory fidelity.

7. pumpkin-command (Command Dispatcher)

• Path: crates/pumpkin-command
• Purpose: Brigadier-inspired hierarchical command tree dispatcher and parser.
• Responsibilities:
  • Constructs modular command trees with typed arguments (Integer, Float, Entity, BlockPos, etc.).
  • Executes permission-checked commands.
  • Provides real-time autocompletion suggestions sent to connected clients.

8. pumpkin-auth (Authentication & Session Verification)

• Path: crates/pumpkin-auth
• Purpose: Cryptographic authentication and player identity verification.
• Responsibilities:
  • Validates client sessions with Mojang's Yggdrasil authentication servers.
  • Handles RSA keypair generation and shared secret exchange during the Login state.
  • Supports offline-mode UUID generation and custom authentication endpoints.
  • Implements proxy forwarding protocols: BungeeCord, BungeeGuard, and Velocity modern forwarding with HMAC-SHA256 signatures.

9. pumpkin-nbt (Named Binary Tag Codec)

• Path: crates/pumpkin-nbt
• Purpose: High-throughput binary NBT parser and serializer.
• Responsibilities:
  • Parses and encodes all standard NBT tag types (Byte, Short, Int, Long, Float, Double, ByteArray, String, List, Compound, IntArray, LongArray).
  • Supports compression layers: Gzip, Zlib, and uncompressed Network NBT.

10. pumpkin-plugin-* (Extensibility Infrastructure)

• Paths:
  • crates/pumpkin-plugin-api: The Rust developer SDK for compiling native plugins.
  • crates/pumpkin-plugin-runtime: Wasmtime-powered WebAssembly execution host.
  • crates/pumpkin-plugin-wit: WebAssembly Interface Type (WIT) specifications.
  • crates/pumpkin-host-bindings: Auto-generated host bindings connecting Wasmtime and the server core.
• Purpose: Enables safe, polyglot plugin execution (Rust, Python, C#, C, Go, Kotlin) with sandboxed memory and near-native performance.

11. pumpkin-util & pumpkin-macros (Foundations)

• Paths: crates/pumpkin-util, crates/pumpkin-macros, crates/pumpkin-api-macros
• Purpose: Foundational types, shared algorithms, and procedural macros.
• Responsibilities:
  • Mathematical utilities: Vector2, Vector3, BoundingBox, and angle conversions.
  • Text and chat formatting: TextComponent and JSON component serialization.
  • Procedural macros such as #[java_packet(...)] that bind packet structs to protocol IDs and packet traits.

12. tools/ (Developer Tooling)

• tools/pumpkin-codegen: Automated code generator that parses Minecraft version jars, data reports, and asset archives to emit Rust source files into pumpkin-data.
• tools/pumpkin-fuzzer: Fuzz testing suites for network packet parsers, NBT readers, and region file decoders to identify potential crash vectors or memory anomalies.

---

Concurrency & Threading Model

Component	Runtime / Pool	Primary Workload	Communication Mechanism
Network & Socket I/O	Tokio Async Runtime	TCP packet reads, Bedrock UDP packets, framing, session handshakes	Async tasks (tokio::spawn), non-blocking reactors
Heavy Compute	Rayon Thread Pool	Terrain generation, noise routers, light propagation, chunk compression	Worker threads via crossbeam / Rayon iterators
Inter-Thread Bridge	Tokio Channels	Dispatching completed chunks and encoded packets back to network tasks	Non-blocking tokio::sync::mpsc channels

Pumpkin strictly adheres to this separation of concerns:

• I/O Bound: Managed on Tokio asynchronous tasks.
• CPU Bound: Managed on Rayon thread pools.
• Communication: Coordinated via cross-thread channels (tokio::sync::mpsc) without ever blocking the Tokio reactor loop.