从 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）：

:::code-group

# 带有 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

# 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 内部机制的参数均不适用，且无法传递给程序。

管理员检查清单

备份现有服务器数据和世界文件，并确保世界与数据包已升级到最新格式（例如通过客户端的“优化世界”）。
将 server.properties 中的设置映射至 pumpkin.toml。
确定所需插件并寻找 WebAssembly（.wasm）替代，或使用 PatchBukkit 进行测试。
若使用代理网络，在 pumpkin.toml 中配置代理设置（Velocity / BungeeCord）。
更新启动脚本以直接运行 ./pumpkin，无需传入 JVM 参数。
启动服务器并检查连接和日志。

6.0 KiB Raw Permalink Blame History Unescape Escape