57 lines
3.2 KiB
Markdown
57 lines
3.2 KiB
Markdown
# Plugin Engine Architecture
|
|
|
|
Pumpkin features a modular, multi-runtime plugin engine designed for performance, safety, and cross-language interoperability.
|
|
|
|
Unlike traditional Minecraft servers that rely on a single JVM class loader, Pumpkin isolates plugin execution through dedicated loaders supporting both **native high-performance Rust binaries** and **sandboxed WebAssembly components** compiled from Rust, Python, C#, C, Go, or Kotlin.
|
|
|
|
---
|
|
|
|
## Architectural Overview
|
|
|
|
### Architectural Breakdown
|
|
|
|
| Subsystem | Primary Crate | Responsibility |
|
|
| :--- | :--- | :--- |
|
|
| **Plugin Manager** | `crates/pumpkin/src/plugin` | Lifecycle orchestration (load, enable, disable), event dispatching, and loader registration |
|
|
| **Native Loader** | `crates/pumpkin/src/plugin/loader/native` | Direct dynamic library loading (`.so`, `.dll`, `.dylib`) for zero-overhead Rust extensions |
|
|
| **WASM Loader** | `crates/pumpkin/src/plugin/loader/wasm` | Wasmtime execution engine for sandboxed components compiled from Rust, Python, Go, C#, C, and Kotlin |
|
|
| **Interface Specifications** | `crates/pumpkin-plugin-wit` | WebAssembly Interface Types (WIT) defining typed functions, types, and host imports |
|
|
| **Security & Verification** | `crates/pumpkin/src/plugin/loader/wasm/sign` | Cryptographic signature verification via W3C wasmsign2 / Ed25519 public keys |
|
|
|
|
---
|
|
|
|
## The Dual Execution Model
|
|
|
|
| Feature | Native Plugins | WebAssembly (Wasmtime) Plugins |
|
|
| :--- | :--- | :--- |
|
|
| **File Extension** | `.so` (Linux), `.dll` (Windows), `.dylib` (macOS) | `.wasm` (Component Model) |
|
|
| **Languages** | Rust (compiled dynamically) | Rust, Python, C#, C, Go, Kotlin |
|
|
| **Performance** | Native CPU execution (zero overhead) | JIT-compiled with near-native speed |
|
|
| **Sandboxing** | None (runs in host address space) | Memory-isolated sandboxed execution |
|
|
| **Security & Signing** | OS-level permissions | Cryptographic W3C Wasm-Sign verification |
|
|
| **Hot Unloading** | Limited (OS shared library constraints) | Fully supported memory reclamation |
|
|
|
|
---
|
|
|
|
## Event Lifecycle & Dispatching
|
|
|
|
Plugins interact with Pumpkin primarily through events:
|
|
|
|
1. **Event Dispatch**:
|
|
- `server.plugin_manager.fire_blocking(&server, &mut event)`: Dispatches events synchronously on the executing thread (e.g., cancelling player block placement or modifying packet payloads).
|
|
- Asynchronous events run on non-blocking Tokio tasks.
|
|
2. **Cancellable Events**:
|
|
- Handlers can set `event.cancelled = true` to abort the default game logic (such as cancelling player movement, interactions, or packet processing).
|
|
|
|
---
|
|
|
|
## Plugin Engine Documentation
|
|
|
|
Explore the internal mechanics of Pumpkin's plugin system:
|
|
|
|
- **[Adding a Plugin Loader](/developer/plugins/loaders)**: Step-by-step guide on implementing the `PluginLoader` trait for new scripting languages and runtimes.
|
|
- **[WASM Signing & Verification](/developer/plugins/wasm-signing)**: Detailed specification of Ed25519 cryptographic signing, W3C `wasmsign2` custom sections, and marketplace license verification.
|
|
|
|
> [!NOTE]
|
|
> Looking to develop third-party plugins rather than working on Pumpkin's internal plugin engine? Check out the **[Plugin Development Guide](/plugin-dev/introduction)**.
|