Skip to content

從 Bukkit / Spigot / Paper 遷移至 Pumpkin ​

本指南涵蓋將伺服器從 Bukkit、Spigot 或 Paper 遷移至 Pumpkin 時的架構與設定差異。


1. 架構差異 ​

方面Bukkit / Spigot / PaperPumpkin
執行環境Java 虛擬機器(需要 Java 17/21+)原生執行檔(Rust 編譯,無需 Java)
啟動指令java [flags] -jar server.jar./pumpkin
tick 迴圈可將工作分派給非同步工作線程的單線程 tick 迴圈跨 CPU 核心執行多線程 tick
插件格式面向 Bukkit API 的 Java 位元組碼(.jar)WebAssembly(.wasm),或透過 PatchBukkit 支援 .jar
插件開發語言Java、Kotlin、ScalaRust、Python、Kotlin、C#、Go、C
設定檔案server.properties、paper.yml、spigot.ymlpumpkin.toml(TOML 格式)
記憶體管理JVM 垃圾回收(Garbage Collection)原生作業系統記憶體分配

2. 插件與擴充 ​

WebAssembly 插件 ​

Pumpkin 的主要插件格式為 WebAssembly(.wasm):

  • 隔離性:插件在沙箱化的 WebAssembly 執行環境中執行。
  • 語言支援:開發者可以使用 Rust、Python、Go、C#、C 或 Kotlin 將插件編譯為 WASM。
  • 移植插件:關於將自訂 Bukkit 插件移植到 Pumpkin,請參見開發者遷移指南。

Bukkit 插件相容性:PatchBukkit ​

對於依賴現有 Bukkit/Spigot .jar 插件的伺服器,PatchBukkit 項目提供了相容層:

  • 架構:PatchBukkit 在 Pumpkin 內部嵌入了一個 JVM 並重新實現了部分 Bukkit API,透過 JNI 和 FFI 與 Pumpkin 橋接。
  • 插件目錄:相容的 .jar 插件放置在 patchbukkit/patchbukkit-plugins/ 目錄中。
  • 現狀與限制:PatchBukkit 仍在積極開發中。雖然支援標準 Bukkit API 調用,但依賴 NMS(net.minecraft.server)內部類、CraftBukkit 內部實現或位元組碼操作的插件可能無法正常工作。
  • Java 依賴:使用 PatchBukkit 需要在主機系統上安裝 Java 執行環境(JRE/JDK)以執行內嵌的 JVM。

3. 設定與屬性 ​

Pumpkin 使用 TOML 設定檔案替代 server.properties 和 YAML:

Paper / Spigot(server.properties)Pumpkin(pumpkin.toml)
server-port=25565server_address = "0.0.0.0:25565"
motd=...motd = "A Pumpkin Server"
max-players=20max_players = 20
online-mode=trueonline_mode = true
view-distance=10view_distance = 10
simulation-distance=8simulation_distance = 8

4. 世界與資料儲存 ​

  • 格式相容性:Pumpkin 支援標準的 Anvil 區塊格式(.mca 檔案)。
  • 目錄結構:從現有的 Paper/Spigot 複製世界時,請確保維度目錄(world、world_nether、world_the_end)與 Pumpkin 的目錄佈局相符。
  • 需要最新的世界與資料包格式:至少在目前階段,Pumpkin 僅支援對應目標 Minecraft 版本的最新世界格式和資料包格式。執行時不會自動轉換舊版世界格式或舊版資料包。
    • 在客戶端中升級世界:如果要遷移較舊的世界,請在 Pumpkin 中載入前先進行升級。你可以直接在官方 Minecraft 客戶端中更新世界:使用匹配的最新版本開啟客戶端,進入單人遊戲,選擇該世界,點選編輯並選擇優化世界。或者,也可以在匹配最新版本的原版伺服器上執行一次該世界。
    • 資料包:確保 world/datapacks 中的所有自訂資料包均已更新到目標版本所要求的格式版本。

5. 啟動與 JVM 標誌 ​

無需安裝 Java ​

純淨的 Pumpkin 是一個獨立的自包含原生執行檔。執行該伺服器不需要在系統或容器中安裝 Java 執行環境(JRE/JDK)。

啟動指令對比 ​

Paper 和 Spigot 伺服器通常使用帶有堆記憶體分配和垃圾回收參數的 JVM 啟動指令碼(如 Aikar's Flags):

bash
# 帶有 Aikar's Flags 的典型 Paper 啟動指令:
java -Xms10G -Xmx10G \
  -XX:+UseG1GC \
  -XX:+ParallelRefProcEnabled \
  -XX:MaxGCPauseMillis=200 \
  -XX:+UnlockExperimentalVMOptions \
  -XX:+DisableExplicitGC \
  -XX:+AlwaysPreTouch \
  -XX:G1NewSizePercent=30 \
  -XX:G1MaxNewSizePercent=40 \
  -XX:G1HeapRegionSize=8M \
  -XX:G1ReservePercent=20 \
  -XX:G1HeapWastePercent=5 \
  -XX:G1MixedGCCountTarget=4 \
  -XX:InitiatingHeapOccupancyPercent=15 \
  -XX:G1MixedGCLiveThresholdPercent=90 \
  -XX:G1RSetUpdatingPauseTimePercent=5 \
  -XX:SurvivorRatio=32 \
  -XX:+PerfDisableSharedMem \
  -XX:MaxTenuringThreshold=1 \
  -Dusing.aikars.flags=https://mcflags.emc.gs \
  -Daikars.new.flags=true \
  -jar paper.jar --nogui
bash
# Linux / macOS:
./pumpkin

# Windows:
./pumpkin.exe

# Docker:
docker run -p 25565:25565 -v ./data:/data pumpkinmc/pumpkin:latest

記憶體機制差異 ​

  • 無垃圾回收器:Pumpkin 由 Rust 編寫,在編譯階段使用確定性的記憶體管理(RAII)。不存在執行階段的垃圾回收器,因此無需調優 GC 停頓。
  • 無需固定堆記憶體:原生程式中不存在 -Xms 和 -Xmx 標誌。記憶體根據區塊和實體的載入動態向作業系統申請,卸載後立即釋放。
  • JVM 標誌不適用:用於調優垃圾回收策略、分代大小或 JVM 內部機制的參數均不適用,且無法傳遞給程式。

管理員檢查清單 ​

基於 MIT 授權條款發布。