从 Bukkit / Spigot / Paper 迁移至 Pumpkin
本指南涵盖将服务器从 Bukkit、Spigot 或 Paper 迁移至 Pumpkin 时的架构与配置差异。
1. 架构差异
| 方面 | Bukkit / Spigot / Paper | Pumpkin |
|---|---|---|
| 运行时环境 | 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、Scala | Rust、Python、Kotlin、C#、Go、C |
| 配置文件 | server.properties、paper.yml、spigot.yml | pumpkin.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=25565 | server_address = "0.0.0.0:25565" |
motd=... | motd = "A Pumpkin Server" |
max-players=20 | max_players = 20 |
online-mode=true | online_mode = true |
view-distance=10 | view_distance = 10 |
simulation-distance=8 | simulation_distance = 8 |
4. 世界与数据存储
- 格式兼容性：Pumpkin 支持标准的 Anvil 区块格式（
.mca文件）。 - 目录结构：从现有的 Paper/Spigot 复制世界时，请确保维度目录（
world、world_nether、world_the_end）与 Pumpkin 的目录布局相符。 - 需要最新的世界与数据包格式：至少在目前阶段，Pumpkin 仅支持对应目标 Minecraft 版本的最新世界格式和数据包格式。运行时不会自动转换旧版世界格式或旧版数据包。
- 在客户端中升级世界：如果要迁移较旧的世界，请在导入 Pumpkin 前先进行升级。您可以直接在官方 Minecraft 客户端中更新世界：使用匹配的最新版本打开客户端，进入单人游戏，选择该世界，点击编辑并选择优化世界。或者，您也可以在匹配最新版本的原版/Paper 服务器中启动并保存一次该世界。
- 数据包：确保
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 --noguibash
# 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 内部机制的参数均不适用，且无法传递给程序。