EsbpmPlugin API 文档

插件概览

EsbpmPlugin 是一个基于 Paper API 开发的 Minecraft 插件，提供了多项功能来增强服务器管理和玩家体验。本文档提供了插件的技术实现细节，供开发者参考和扩展。

项目结构

├── pom.xml               # Maven 项目配置文件
├── src/main/java/com/esbpm/plugin/
│   └── EsbpmPlugin.java  # 插件主类
├── src/main/resources/
│   ├── config.yml        # 插件配置文件模板
│   └── plugin.yml        # 插件元数据配置
└── docs/                 # 文档目录
    ├── README.md         # 用户文档
    └── API.md            # 开发者API文档

插件主类

插件的所有功能都集中在 EsbpmPlugin 类中，该类继承自 JavaPlugin 并实现了 Listener 接口。

java

public class EsbpmPlugin extends JavaPlugin implements Listener {
    // 类成员和方法
}

核心成员变量

java

private Set<UUID> flyingPlayers = new HashSet<>();  // 存储正在飞行的玩家UUID
private Set<String> bannedItems = new HashSet<>();  // 存储被禁止的物品类型

生命周期方法

onEnable()

当插件被启用时调用，初始化插件并注册事件监听器。

参数：无 返回值：无

java

@Override
public void onEnable() {
    // 注册事件监听器
    Bukkit.getPluginManager().registerEvents(this, this);
    
    // 初始化禁止物品列表
    initializeBannedItems();
    
    // 保存默认配置文件
    saveDefaultConfig();
    
    getLogger().info("EsbpmPlugin 已启用!");
}

onDisable()

当插件被禁用时调用，执行清理工作。

参数：无 返回值：无

java

@Override
public void onDisable() {
    getLogger().info("EsbpmPlugin 已禁用!");
}

命令处理

onCommand()

处理插件注册的命令，当前只实现了 /fly 命令。

参数：

sender: 命令发送者 (CommandSender)
command: 命令对象 (Command)
label: 命令标签 (String)
args: 命令参数数组 (String[])

返回值：boolean - 表示命令是否执行成功

java

@Override
public boolean onCommand(CommandSender sender, Command command, String label, String[] args) {
    if (command.getName().equalsIgnoreCase("fly")) {
        // 飞行命令处理逻辑
        // ...
        return true;
    }
    return false;
}

事件监听器

插件实现了多个事件监听器来处理玩家的各种行为：

onPlayerJoin

当玩家加入服务器时触发，应用速度效果并设置游戏模式。

java

@EventHandler
public void onPlayerJoin(PlayerJoinEvent event) {
    // 处理玩家加入事件
    // ...
}

onPlayerQuit

当玩家离开服务器时触发，清理玩家的飞行状态。

java

@EventHandler
public void onPlayerQuit(PlayerQuitEvent event) {
    // 处理玩家离开事件
    // ...
}

onPlayerChangedWorld

当玩家切换世界时触发，重新应用速度效果。

java

@EventHandler
public void onPlayerChangedWorld(PlayerChangedWorldEvent event) {
    // 处理玩家切换世界事件
    // ...
}

onPlayerInteract

当玩家与物品交互时触发，检查并阻止使用被禁止的物品。

java

@EventHandler
public void onPlayerInteract(PlayerInteractEvent event) {
    // 处理玩家交互事件
    // ...
}

onGameModeChange

当玩家尝试更改游戏模式时触发，检查并限制游戏模式更改。

java

@EventHandler
public void onGameModeChange(PlayerGameModeChangeEvent event) {
    // 处理游戏模式更改事件
    // ...
}

工具方法

getGameModeName

将 GameMode 枚举转换为中文名称。

参数：mode - 游戏模式枚举值 (GameMode) 返回值：String - 游戏模式的中文名称

java

private String getGameModeName(GameMode mode) {
    switch (mode) {
        case SURVIVAL: return "生存模式";
        case CREATIVE: return "创造模式";
        case ADVENTURE: return "冒险模式";
        case SPECTATOR: return "旁观模式";
        default: return "未知模式";
    }
}

initializeBannedItems

初始化被禁止的物品列表。

参数：无 返回值：无

java

private void initializeBannedItems() {
    // 添加危险物品到禁止列表
    bannedItems.add("TNT");
    bannedItems.add("TNT_MINECART");
    bannedItems.add("ENDER_PEARL");
    bannedItems.add("END_CRYSTAL");
    bannedItems.add("FLINT_AND_STEEL");
    bannedItems.add("LAVA_BUCKET");
    bannedItems.add("BUCKET"); // 防止放置水/岩浆
}

配置项详解

插件的配置文件 config.yml 包含以下可配置项：

speed-effect 部分

控制速度效果的设置

配置项	类型	默认值	描述
enabled	boolean	true	是否启用速度效果
level	integer	2	速度等级 (1-5)

flight 部分

控制飞行相关的设置

配置项	类型	默认值	描述
allow-in-survival	boolean	true	是否允许在生存模式下飞行

gamemode 部分

控制游戏模式相关的设置

配置项	类型	默认值	描述
forced-mode	integer	2	强制非管理员玩家的游戏模式 (0=生存, 1=创造, 2=冒险, 3=旁观)
enabled	boolean	true	是否启用强制游戏模式功能

权限节点

插件使用以下权限节点控制玩家的操作权限：

权限节点	描述	默认值
esbpm.fly	允许使用飞行命令	true（所有玩家）
esbpm.gamemode.bypass	允许绕过游戏模式限制	op（仅管理员）

插件元数据配置

插件的 plugin.yml 配置文件定义了插件的基本信息和注册的命令：

yaml

name: EsbpmPlugin
version: 1.0
main: com.esbpm.plugin.EsbpmPlugin
api-version: 1.21
author: Lingma
description: 一个提供飞行命令、速度效果和危险物品限制的插件
commands:
  fly:
    description: 切换飞行模式
    usage: /fly
    permission: esbpm.fly
permissions:
  esbpm.fly:
    description: 允许使用飞行命令
    default: true
  esbpm.gamemode.bypass:
    description: 允许绕过游戏模式限制
    default: op

Maven 依赖配置

插件使用 Maven 管理依赖，主要依赖如下：

xml

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

扩展指南

如需扩展插件功能，建议考虑以下方向：

添加新命令：在 onCommand 方法中添加新的命令处理逻辑，并在 plugin.yml 中注册新命令
自定义被禁止物品：将被禁止物品列表从硬编码改为可配置项
添加更多权限节点：为不同功能添加更细粒度的权限控制
添加数据持久化：保存玩家的飞行状态和其他设置，使其在重新登录后保持
添加更多功能：如传送系统、经济系统、聊天管理等

注意事项

本插件基于 Paper API 开发，可能与 Spigot 或 Bukkit 服务端不完全兼容
修改配置文件后，需要重启服务器使更改生效
添加新功能时，请确保正确注册事件监听器和命令
注意保持代码风格一致，并添加适当的注释

EsbpmPlugin API 文档 ​

插件概览 ​

项目结构 ​

插件主类 ​

核心成员变量 ​

生命周期方法 ​

onEnable() ​

onDisable() ​

命令处理 ​

onCommand() ​

事件监听器 ​

onPlayerJoin ​

onPlayerQuit ​

onPlayerChangedWorld ​

onPlayerInteract ​

onGameModeChange ​

工具方法 ​

getGameModeName ​

initializeBannedItems ​

配置项详解 ​

speed-effect 部分 ​

flight 部分 ​

gamemode 部分 ​

权限节点 ​

插件元数据配置 ​

Maven 依赖配置 ​

扩展指南 ​

注意事项 ​

EsbpmPlugin API 文档

插件概览

项目结构

插件主类

核心成员变量

生命周期方法

onEnable()

onDisable()

命令处理

onCommand()

事件监听器

onPlayerJoin

onPlayerQuit

onPlayerChangedWorld

onPlayerInteract

onGameModeChange

工具方法

getGameModeName

initializeBannedItems

配置项详解

speed-effect 部分

flight 部分

gamemode 部分

权限节点

插件元数据配置

Maven 依赖配置

扩展指南

注意事项