PaperMC插件开发

2025-08-02

开发环境部署🔗

安装 JDK： Java Development Kit Downloads ，版本以目标 Paper 服务端要求为准。

JDK 下载页面

安装 IDE： IntelliJ IDEA Community Edition 下载安装 ，社区版免费，适合个人开发。

IntelliJ IDEA 下载

可选安装 Minecraft 开发插件： Minecraft Development ，提供 Paper 工程和资源文件的代码提示。

Minecraft Development 插件

Minecraft Development 插件安装

在 IDE 中新建 Maven 工程，再按下面的结构创建文件。

创建插件工程

最小插件工程🔗

PaperMC 插件本质上是一个 JAR，服务端通过 plugin.yml 找到主类并加载。先建立最简工程：

myplugin/
├── pom.xml
└── src/main/
    ├── java/com/example/myplugin/
    │   ├── MyPlugin.java
    │   └── PlayerListener.java
    └── resources/plugin.yml

plugin.yml🔗

src/main/resources/plugin.yml：

name: MyPlugin
version: 1.0.0
main: com.example.myplugin.MyPlugin
api-version: "1.21"

commands:
  hello:
    description: 发送一条测试消息
    usage: /hello

main 必须指向主类完整类名，写错会导致服务端启动时拒绝加载插件。

主类🔗

src/main/java/com/example/myplugin/MyPlugin.java：

package com.example.myplugin;

import org.bukkit.plugin.java.JavaPlugin;

public final class MyPlugin extends JavaPlugin {

    @Override
    public void onEnable() {
        getLogger().info("MyPlugin enabled");
        getServer().getPluginManager().registerEvents(new PlayerListener(), this);
        getCommand("hello").setExecutor((sender, command, label, args) -> {
            sender.sendMessage("Hello from MyPlugin");
            return true;
        });
    }

    @Override
    public void onDisable() {
        getLogger().info("MyPlugin disabled");
    }
}

事件监听器🔗

src/main/java/com/example/myplugin/PlayerListener.java：

package com.example.myplugin;

import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.event.player.PlayerJoinEvent;

public final class PlayerListener implements Listener {

    @EventHandler
    public void onPlayerJoin(PlayerJoinEvent event) {
        event.getPlayer().sendMessage("欢迎回到服务器");
    }
}

Maven 构建配置🔗

pom.xml 示例（版本号按目标服务端版本调整，示例使用 1.21.4 API）：

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.example</groupId>
    <artifactId>myplugin</artifactId>
    <version>1.0.0</version>
    <packaging>jar</packaging>

    <properties>
        <maven.compiler.release>21</maven.compiler.release>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <repositories>
        <repository>
            <id>papermc</id>
            <url>https://repo.papermc.io/repository/maven-public/</url>
        </repository>
    </repositories>

    <dependencies>
        <dependency>
            <groupId>io.papermc.paper</groupId>
            <artifactId>paper-api</artifactId>
            <version>1.21.4-R0.1-SNAPSHOT</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>

    <build>
        <finalName>MyPlugin</finalName>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.13.0</version>
            </plugin>
        </plugins>
    </build>
</project>

provided 表示编译时使用 Paper API，打包时不把服务端已有的类塞进插件 JAR。插件如果引入第三方库，需要额外配置 shade/relocation。

构建与调试🔗

mvn clean package
cp target/MyPlugin.jar /path/to/server/plugins/

然后重启服务端，不要用 /reload。查看 logs/latest.log 中是否有 MyPlugin enabled 或堆栈信息。

调试方式：

先在本地开一个 Paper 服务端，把插件 JAR 放进 plugins/，确认基础功能。
使用 IDE 的远程调试功能附加到服务端 JVM，断点调试事件和命令逻辑。
官方调试说明见 PaperMC Debugging 。

发布到 Hangar🔗

发布前确认插件名、版本、支持的核心和 api-version。Hangar 发布流程参考 Hangar Publishing 。

两个现成插件项目可供参考： OrzMCPlugin / GetMeHome 。