Paper：高性能 Minecraft 服务端项目实战指南

Paper高性能 Minecraft 服务端项目实战指南【免费下载链接】PaperThe most widely used, high performance Minecraft server that aims to fix gameplay and mechanics inconsistencies项目地址: https://gitcode.com/GitHub_Trending/pa/Paper导读本文以 Paper 仓库的 README.md 为主体系统讲解该高性能 Minecraft 服务端的三大核心用法服务端管理员如何下载并运行 Paperclip 一键启动包、插件开发者如何通过 Gradle/Maven 接入 Paper API 进行插件开发以及开发者如何从源码编译出完整的可运行 Jar。全文结合仓库源码结构、构建配置与补丁体系帮助你从会运行深入到懂原理。一、Paper 是什么Paper 是一个使用最广泛、高性能的 Minecraft 服务端其核心目标是修复原版游戏在玩法与机制上的不一致性问题gameplay and mechanics inconsistencies。它基于 Spigot 生态演进而来向下兼容 Bukkit/Spigot 插件同时提供了大量面向插件开发者的新增 API 与性能优化。从仓库结构看项目由以下几个核心模块构成见 settings.gradle.kts模块作用paper-api插件开发者依赖的公共 API 模块含事件、实体、方块、数据组件等大量接口paper-server服务端实现模块包含对 Minecraft 源码的补丁patches与 CraftBukkit 实现paper-checkstyle代码风格检查工具模块paper-generator数据/注册表生成器可选模块默认关闭test-plugin用于测试 API 变更的测试插件可选模块当前仓库对应的版本信息定义在 gradle.properties 中mcVersion26.2、apiVersion26.2、channelSTABLE。构建版本号由 settings.gradle.kts 动态生成无BUILD_NUMBER环境变量时为26.2.local-SNAPSHOTCI 环境下则为26.2.build.编号-stable形式。二、服务端管理员下载与运行 PaperclipPaper 的发布形态是Paperclip——一个可直接像普通 Jar 一样运行的打包文件。使用流程非常简单从官方下载页面获取 Paper 的最新构建选择与你的 Minecraft 版本匹配的构建将下载的 Paperclip Jar 直接放到服务器目录使用java -jar命令启动即可无需任何额外安装步骤。java -jar paper-26.2-xxx.jar --nogui首次启动时 Paperclip 会自动解压并初始化服务端文件生成eula.txt、server.properties、config/paper-global.yml等修改eula.txt中的eulatrue后重新启动即可进入正常服务流程。从源码视角理解 Paperclip 启动入口Paper 服务端的实际主类是org.bukkit.craftbukkit.Main定义于 paper-server/src/main/java/org/bukkit/craftbukkit/Main.java。在 paper-server/build.gradle.kts 的 Jar 打包配置中Manifest 明确写入了Main-Class to org.bukkit.craftbukkit.Main并携带Implementation-Version如26.2-DEV-git短哈希、Brand-Idpapermc:paper、Git-Commit等元信息——这也是服务端启动时能显示精确版本号的原因。paper-server模块还注册了多组本地调试运行任务group 为runsGradle 任务说明runServer从 Mojang 映射后的服务端 Jar 启动测试服务器runDevServer不组装 Jar直接用 classpath 启动便于断点调试runBundler/runPaperclip分别从 bundler Jar 与 Paperclip Jar 启动这些任务默认在仓库根目录下的run/工作目录运行由paper.runWorkDir属性控制内存默认 2Gpaper.runMemoryGb可调并会自动挂载test-plugin模块的 Jar通过-add-plugin参数方便插件开发者在真实服务端环境中验证 API 变更。三、插件开发者接入 Paper APIPaper 提供了独立发布的paper-api依赖插件只需面向 API 编译运行期由服务端提供实现。API 源码位于 paper-api 目录其中io.papermc.paper包下包含大量扩展 API如 event、datacomponent、registry 等org.bukkit包则是完整的 Bukkit 兼容 API。Gradle 接入方式repositories { maven { url uri(https://repo.papermc.io/repository/maven-public/) } } dependencies { compileOnly(io.papermc.paper:paper-api:26.2.build.) } java { toolchain.languageVersion.set(JavaLanguageVersion.of(25)) }要点说明仓库地址使用 PaperMC 官方的 Maven 公共仓库配置在 paper-server/build.gradle.kts 中的paperMavenPublicUrl与此一致依赖作用域必须是compileOnlyGradle/providedMaven因为运行期服务端已内置 API 实现避免重复打包版本通配符26.2.build.会自动拉取该版本线的最新构建插件编译目标为 JDK 25与当前仓库构建要求一致。Maven 接入方式repository idpapermc/id urlhttps://repo.papermc.io/repository/maven-public//url /repositorydependency groupIdio.papermc.paper/groupId artifactIdpaper-api/artifactId version[26.2.build,)/version scopeprovided/scope /dependency本地调试test-plugin 模块如果你正在参与 Paper 本身的 API 开发可以利用仓库自带的 test-plugin 模块快速验证在test-plugin.settings.gradle.kts中取消注释启用该模块首次运行 Gradle 后会自动生成此文件修改测试插件代码后执行./gradlew runDev或其他 run 任务服务端启动时便会自动加载该插件。测试插件包含 TestPlugin.java、TestPluginBootstrap与TestPluginLoader三个核心类覆盖了 Paper 现代插件加载机制的三种角色。此外若要在本地 Maven 仓库安装 API 供外部插件调试可运行./gradlew publishToMavenLocal。四、开发者从源码编译 Paper Jar环境要求JDK 25编译 Paper 必需。不过由于使用了 Gradle Toolchains 机制本地只安装 JRE 21 也可以构建——Gradle 会自动下载并临时配置 JDK 25 用于编译详见 CONTRIBUTING.md网络连接首次构建需拉取 Minecraft 反编译源码mache、依赖与 Gradle 插件必须通过 Git 克隆仓库settings.gradle.kts中做了显式检查若目录不是合法的 Git 克隆如直接下载 zip 解压构建会直接报错提示。编译步骤# 1. 克隆并进入仓库 git clone https://gitcode.com/GitHub_Trending/pa/Paper cd Paper # 2. 应用补丁 ./gradlew applyPatches # 3. 生成可运行的 Paperclip Jar ./gradlew createPaperclipJar # 4. 查看所有可用任务 ./gradlew tasks编译产物位于paper-server/build/libs目录即为可直接运行的 Paperclip Jar。注意 Windows 下需去掉命令开头的./直接使用gradlew.bat applyPatches。补丁体系Paper 源码的组织方式Paper 对 Minecraft 原版源码的修改不直接改源码而是通过补丁patches维护主要分三类见 paper-server/patches 目录类型目录说明sourcespaper-server/patches/sources针对单个 Minecraft 类的逐文件补丁resourcespaper-server/patches/resources针对 Minecraft 数据文件的逐文件补丁featurespaper-server/patches/features跨多个类的大型特性补丁如0001-Moonrise-optimisation-patches.patch、0002-Rewrite-dataconverter-system.patch、0012-Eigencraft-redstone-implementation.patch等features目录中的补丁尤其能体现 Paper 的性能优化思路从 Moonrise 区块优化、数据转换器重写、实体激活范围 2.0、反 X-Ray、漏斗优化到 Eigencraft/Alternate Current 红石实现等均为可选剥离的大型补丁便于在 Minecraft 大版本更新时暂时摘除、后续重新应用可参见 CONTRIBUTING.md 对 feature patch 的说明。相关开发任务速查任务用途./gradlew applyPatches将 patches 应用到反编译源码生成paper-server/src/minecraft工作区./gradlew fixupSourcePatches修改单文件补丁后回写补丁文件./gradlew rebuildPatches根据源码工作区重新生成补丁./gradlew createPaperclipJar组装最终的 Paperclip 可运行 Jar./gradlew publishToMavenLocal将 API/Server 安装到本地 Maven 仓库./gradlew runDev系列直接启动调试服务端自动加载 test-plugin仓库还提供了 scripts/apatch.sh 补丁应用辅助脚本支持--noapplied、--reset等参数可在补丁应用失败时用git apply --rej wiggle 的方式摇晃合入并输出失败摘要供高级用户排查补丁冲突。五、参与贡献Pull Request 流程与配置项扩展如果你希望为 Paper 提交代码请先阅读 CONTRIBUTING.md。其中最重要的几条规则使用个人 fork 而非组织仓库提交 PR因为 Paper 维护者会直接在 PR 上做 rebase 与微调修改 Minecraft 原版代码必须做标记注释多行改动用// Paper start - 描述与// Paper end - 描述包裹单行改动在行尾加// Paper - 描述这是跨文件追踪 Paper 变更的关键约定新增可配置项走 Configuration 体系全局配置在io.papermc.paper.configuration.GlobalConfiguration世界级配置在WorldConfiguration。字段名默认按 snake-case 映射为配置键例如字段maxNumOfPlayers对应misc.max-num-of-players访问方式为GlobalConfiguration.get().misc.maxNumOfPlayers或通过level.paperConfig().misc.xxx获取世界级配置API 参数校验使用Preconditions#checkArgument抛IllegalArgumentException与Preconditions#checkState抛IllegalStateException避免使用会抛NullPointerException的checkNotNull以便区分内部错误与参数错误。六、版本支持范围与社区对于 1.8 至 1.21.3 的旧版本分支Paper 已将其迁移至归档仓库维护当前主分支只针对最新 Minecraft 版本做活跃开发。如果你需要旧版本请使用归档仓库中的对应分支如果需要新版本特性预览可关注官方项目看板。Paper 的社区支持渠道包括官方论坛与 Discord 服务器。项目还通过 Open Collective 与 GitHub Sponsors 接收捐赠以覆盖基础设施支出所有资金用途公开透明。七、小结围绕 README.md 这条主线本文覆盖了 Paper 的完整使用闭环管理员下载 Paperclip →java -jar直接运行无需额外配置插件开发者通过 Gradle/Maven 以compileOnly/provided方式引入paper-api配合test-plugin与runDev实现本地真机调试源码贡献者JDK 25 Git 克隆 →applyPatches→createPaperclipJar理解 sources/features 双层补丁体系后即可安全修改 Minecraft 源码并回写补丁。无论你是第一次搭建 Paper 服务器的服主、编写插件的开发者还是想深入 Minecraft 服务端优化内核的贡献者本文梳理的构建链路与源码入口settings.gradle.kts、paper-server/build.gradle.kts、paper-server/patches、paper-api都能作为你继续深入阅读的起点。【免费下载链接】PaperThe most widely used, high performance Minecraft server that aims to fix gameplay and mechanics inconsistencies项目地址: https://gitcode.com/GitHub_Trending/pa/Paper创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考