Skip to content

Pumpkin 架構與 Crate ​

Pumpkin 採用模組化 Cargo 工作區組織,由多個專用 crate 組成。每個 crate 都有明確的職責、嚴格定義的邊界和盡可能少的交叉依賴。

這種架構能夠實現高速並行編譯、隔離測試和零成本資料共享,並使網絡協定、遊戲邏輯與世界管理之間保持清晰的分離。


工作區 Crate 概覽 ​

工作區架構一覽 ​

層級Crate職責
核心執行階段pumpkin遊戲迴圈、world tick 更新、玩家會話、實體管理和事件迴圈
網絡與協定pumpkin-protocol、pumpkin-auth、pumpkin-nbtJava 版/基岩版封包序列化、Yggdrasil 與 Xbox Live 身份驗證、SNBT
世界與遊戲玩法pumpkin-world、pumpkin-inventory、pumpkin-command區域 I/O(Anvil/Linear)、地形生成、方塊 tick 更新、容器、Brigadier 指令樹
可擴充性pumpkin-plugin-runtime、pumpkin-host-bindings、pumpkin-plugin-api、pumpkin-plugin-wit透過 Wasmtime 執行 WebAssembly 插件、WIT 主機 API、原生與 WASM 載入器
基礎設施pumpkin-data、pumpkin-config、pumpkin-util程式碼生成的註冊表、類型化設定檔案、數學向量、權限

各 Crate 詳細說明 ​

1. pumpkin(核心伺服器) ​

  • 路徑:crates/pumpkin
  • 用途:主伺服器二進制程式和集中式編排引擎。
  • 職責:
    • 初始化設定、日誌記錄(tracing)和遙測。
    • 為 Minecraft: Java Edition、Minecraft: Bedrock Edition、RCON、Query 和 LAN 廣播啟動 Tokio 網絡監聽器。
    • 管理server tick 迴圈(Server::tick),協調世界更新、玩家操作、實體移動和區塊廣播。
    • 透過 crates/pumpkin/src/net/java/ 和 net/bedrock/ 分派傳入的客戶端封包。
    • 整合插件管理器,在封包處理前後觸發事件處理器。

2. pumpkin-protocol(網絡協定) ​

  • 路徑:crates/pumpkin-protocol
  • 用途:為 Minecraft Java 版和基岩版提供高速網絡傳輸格式序列化與反序列化。
  • 職責:
    • 實現 ClientPacket(序列化)和 ServerPacket(反序列化)trait。
    • 處理協定基礎類型:VarInt、VarLong、UUID、NBT 複合標籤和字符串編解碼器。
    • 實現所有狀態下的封包:Handshake、Status、Login、Config 和 Play。
    • 提供封包壓縮(ZLib/Fast 壓縮)和封包加密(AES-128/CFB8)。
    • 封裝 RCON 和 GameSpy4 Query 協定。

3. pumpkin-world(世界與區塊) ​

  • 路徑:crates/pumpkin-world
  • 用途:世界載入、儲存、地形生成和區塊管理。
  • 職責:
    • 支援多種區塊儲存格式:
      • 原版 Anvil(.mca):讀取和寫入標準區域檔案。
      • Linear(.linear):採用 zstd 壓縮的高效區域格式,可節省 50–95% 的磁碟空間。
      • Slime(.slime):單檔案世界格式。
      • Pump:Pumpkin 原生區塊儲存格式。
    • 實現世界生成管線:Perlin 噪聲高度圖、3D 噪聲路由器、生物群系氣候參數、已放置地物、雕刻器和超平坦地形。
    • 管理方塊光照和天空光照的傳播。
    • 透過圓柱形區塊迭代器協調區塊載入、卸載和流式傳輸。

4. pumpkin-data(Minecraft 資料集與註冊表) ​

  • 路徑:crates/pumpkin-data
  • 用途:直接根據原版 Minecraft 資源和報告生成的編譯階段靜態註冊表與資料表。
  • 職責:
    • 包含方塊、物品、生物群系、實體、聲音、粒子、附魔和配方的完整 ID 對映、屬性與定義。
    • 跨多個 Minecraft 協定版本查詢封包 ID。
    • 由 tools/pumpkin-codegen 生成的零成本查詢表。

5. pumpkin-config(設定管理) ​

  • 路徑:crates/pumpkin-config
  • 用途:TOML 設定解析、序列化和驗證。
  • 職責:
    • 載入和寫入 pumpkin.toml。
    • 設定伺服器端口、壓縮閾值、代理模式、資源包、日誌級別、世界設定和基岩版整合。
    • 提供安全的預設值和模式驗證。

6. pumpkin-inventory(物品欄與容器) ​

  • 路徑:crates/pumpkin-inventory
  • 用途:服務端容器窗口處理器和物品欄機制。
  • 職責:
    • 管理玩家物品欄、箱子容器、工作臺、熔爐和村民交易界面。
    • 驗證客戶端的欄位點選、拖動操作、物品堆棧和物品拆分。
    • 協調窗口封包同步,確保客戶端物品欄與服務端一致。

7. pumpkin-command(指令分派器) ​

  • 路徑:crates/pumpkin-command
  • 用途:受 Brigadier 啟發的分層指令樹分派器和解析器。
  • 職責:
    • 使用類型化參數(Integer、Float、Entity、BlockPos 等)構建模組化指令樹。
    • 執行經過權限檢查的指令。
    • 向已連線的客戶端提供即時自動自動完成建議。

8. pumpkin-auth(身份驗證與會話校驗) ​

  • 路徑:crates/pumpkin-auth
  • 用途:加密身份驗證和玩家身份核驗。
  • 職責:
    • 透過 Mojang 的 Yggdrasil 身份驗證伺服器驗證客戶端會話。
    • 處理登入狀態下的 RSA 金鑰對生成和共享金鑰交換。
    • 支援離線模式 UUID 生成和自訂身份驗證端點。
    • 實現代理轉發協定:BungeeCord、BungeeGuard,以及使用 HMAC-SHA256 簽名的 Velocity 現代轉發。

9. pumpkin-nbt(命名二進制標籤編解碼器) ​

  • 路徑:crates/pumpkin-nbt
  • 用途:高吞吐量二進制 NBT 解析器和序列化器。
  • 職責:
    • 解析和編碼所有標準 NBT 標籤類型(Byte、Short、Int、Long、Float、Double、ByteArray、String、List、Compound、IntArray、LongArray)。
    • 支援 Gzip、Zlib 壓縮層以及未壓縮的網絡 NBT。

10. pumpkin-plugin-*(可擴充性基礎設施) ​

  • 路徑:
    • crates/pumpkin-plugin-api:用於編譯原生插件的 Rust 開發者 SDK。
    • crates/pumpkin-plugin-runtime:由 Wasmtime 驅動的 WebAssembly 執行主機。
    • crates/pumpkin-plugin-wit:WebAssembly 界面類型(WIT)規範。
    • crates/pumpkin-host-bindings:連線 Wasmtime 與伺服器核心的自動生成主機綁定。
  • 用途:透過沙箱記憶體和接近原生的效能,實現安全的多語言插件執行(Rust、Python、C#、C、Go、Kotlin)。

11. pumpkin-util 與 pumpkin-macros(基礎設施) ​

  • 路徑:crates/pumpkin-util、crates/pumpkin-macros、crates/pumpkin-api-macros
  • 用途:基礎類型、共享演算法和過程巨集。
  • 職責:
    • 數學工具:Vector2、Vector3、BoundingBox 和角度轉換。
    • 文字與聊天格式化:TextComponent 和 JSON 元件序列化。
    • #[java_packet(...)] 等過程巨集,用於將封包結構綁定到協定 ID 和封包 trait。

12. tools/(開發者工具) ​

  • tools/pumpkin-codegen:自動程式碼生成器,解析 Minecraft 版本 JAR、資料報告和資源歸檔,並將 Rust 原始檔輸出到 pumpkin-data。
  • tools/pumpkin-fuzzer:針對網絡封包解析器、NBT 讀取器和區域檔案解碼器的模糊測試套件,用於發現潛在的崩潰途徑或記憶體異常。

並發與線程模型 ​

元件執行階段/線程池主要工作負載通訊機制
網絡與通訊端 I/OTokio 非同步執行環境TCP 封包讀取、基岩版 UDP 封包、幀處理、會話握手非同步任務(tokio::spawn)、非阻塞反應器
繁重計算Rayon 線程池地形生成、噪聲路由器、光照傳播、區塊壓縮透過 crossbeam/Rayon 迭代器執行的工作線程
線程間橋梁Tokio 通道將已完成的區塊和已編碼的封包分派回網絡任務非阻塞 tokio::sync::mpsc 通道

Pumpkin 嚴格遵循以下職責分離原則:

  • I/O 密集型:由 Tokio 非同步任務管理。
  • CPU 密集型:由 Rayon 線程池管理。
  • 通訊:透過跨線程通道(tokio::sync::mpsc)協調,絕不阻塞 Tokio 反應器迴圈。

基於 MIT 授權條款發布。