# 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](https://github.com/SpigotMC/BungeeCord), [BungeeGuard](https://github.com/lucko/BungeeGuard), and [Velocity](https://github.com/PaperMC/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.