140 lines
8.7 KiB
Markdown
140 lines
8.7 KiB
Markdown
# 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.
|