Skip to content

貢獻者文件 ​

歡迎查閱 Pumpkin 的內部貢獻者與開發者文件!

Pumpkin 是一款完全使用現代 Rust 編寫的超高效能、可擴充 Minecraft 伺服器軟體。Pumpkin 從設計之初就注重併發、記憶體安全和原版保真度,同時支援 Minecraft: Java Edition 和 Minecraft: Bedrock Edition。

本節為參與 Pumpkin 伺服器核心、內部 crate 及配套工具開發的貢獻者提供全面的文件。


核心理念與設計原則 ​

Pumpkin 建立在以下幾項基礎工程原則之上:

  • 零成本抽象與極致效能:我們利用 Rust 的零成本抽象、高效記憶體佈局和快取友好的資料結構,盡可能降低 CPU 和記憶體開銷。
  • 嚴格的併發模型:
    • 透過 Tokio 實現非同步 I/O:網路通訊端處理、用戶端握手、封包流式傳輸和檔案 I/O 均在非同步執行環境中高效執行。
    • 透過 Rayon 實現平行計算:地形生成、光照計算、區塊序列化和物理計算等繁重的 CPU 密集型任務會分派到 Rayon 執行緒池,避免阻塞非同步網路迴圈。
    • 執行緒安全通訊:非阻塞通道(tokio::sync::mpsc、crossbeam)在非同步任務與執行緒池之間無縫協調工作。
  • 可靠的品質保障與無 panic 執行:Pumpkin 強制執行嚴格的 Clippy 規則。在生產伺服器程式碼中,panic、unwrap()、expect() 和未處理的錯誤都會在編譯階段被禁止。
  • 模組化工作區架構:各項功能清晰地劃分到職責專一的 crate 中(pumpkin-protocol、pumpkin-world、pumpkin-inventory、pumpkin-command、pumpkin-data 等)。每個 crate 都有明確的職責和清晰的依賴邊界。
  • 協定保真度:我們力求嚴格相容原版,同時提供 Linear 區域格式支援、基岩版跨平臺連線和多語言 WebAssembly 插件執行環境等現代功能。

文件導航 ​

瀏覽貢獻者文件,瞭解 Pumpkin 的工作方式以及如何高效地參與貢獻:

章節說明
貢獻指南環境搭建、建構、測試、Clippy 規則和 PR 規範的分步說明。
架構與 Crate深入介紹 Pumpkin 的多 crate 工作區結構、各 crate 的職責以及資料流。
資料提取器透過我們的 Fabric 模組提取硬編碼的原版 Minecraft 註冊表、邊界框和封包結構。
網路概述核心網路架構、傳輸方式和多版本支援。
Java 版網路協定狀態、新增封包和身分驗證。
基岩版網路RakNet/NetherNet 傳輸、新增封包、身分驗證和 NetherNet。
代理轉發為 BungeeCord、Velocity 和 Vine 提供安全的玩家資訊轉發。
Query 協定面向外部監控機器人和伺服器列表的 GameSpy4 UDP 查詢實現。
方塊方塊架構、方塊狀態、碰撞、屬性以及新增方塊行為。
物品物品架構、資料元件、食物、冷卻時間以及新增物品行為。
實體與生物實體 trait 層次結構、生成與追蹤,以及生物 AI 與路徑尋找。
指令純 Rust 的 Brigadier 指令樹、新增指令、引數與建議,以及執行上下文。
插件引擎內部插件引擎架構、新增插件載入器,以及 WASM 簽名與許可。
世界引擎與格式區塊載入、儲存、Anvil/Linear/Slime/Pump 格式、地形生成和光照。
程式碼生成tools/pumpkin-codegen 如何處理原版 Minecraft 資料並生成 pumpkin-data。
移植 Minecraft 版本升級 Pumpkin 的端到端指南:資料提取、資源與資料包、程式碼生成、編譯器修復、新的方塊/物品/實體邏輯,以及 ViaVersion 重對映。
行動裝置開發在 Android(Termux)等行動裝置環境中開發和編譯 Pumpkin。

插件開發與核心開發 ​

NOTE

如果你希望開發用於擴充 Pumpkin 的第三方插件,而不是為伺服器本身做貢獻,請查閱專門的 插件開發 章節。

依託我們的 WebAssembly(Wasmtime)執行階段和 WIT 介面,Pumpkin 支援使用 Rust、Python、C#、C、Go 和 Kotlin 編寫插件。

基於 MIT 授權條款釋出。