[Bukkit插件开发]手持发射器箭矢机枪 教学文档 面向Python/C#开发者入门Java与Bukkit API

面向Python/C#开发者入门Java与Bukkit API

欢迎来到Minecraft服务器插件开发的世界！如果你熟悉Python或C#，那么你已经掌握了编程的基本思维。本教程将以一个酷炫的“手持发射器箭矢机枪”功能为例，引导你理解Java语言基础、Bukkit API的核心概念，并最终构建你自己的插件。

我们将通过分析一个具体的Java代码文件，一步步揭示其工作原理，并帮助你将现有的编程知识迁移到Java和Bukkit生态系统中。

---

目录

1. 引言：从Python/C#到Java与Bukkit
2. 准备工作：搭建开发环境
   • 2.1 Java Development Kit (JDK)
   • 2.2 集成开发环境 (IDE)
   • 2.3 构建工具 (Maven/Gradle)
   • 2.4 Bukkit/Spigot/PaperMC 服务器
3. 核心概念速览：Java与Bukkit特有之处
   • 3.1 Java语言特性与Python/C#的对比
   • 3.2 Bukkit API核心：事件、监听器、调度器
   • 3.3 项目结构：pom.xml与plugin.yml
4. 代码深度解析：箭矢机枪功能实现
   • 4.1 类定义与构造函数
   • 4.2 onPlayerInteract：玩家交互事件监听
   • 4.3 核心：Bukkit调度器与持续射击任务
   • 4.4 箭矢生成、消耗与扩散逻辑
   • 4.5 停止射击的条件与清理
   • 4.6 辅助方法：查找箭矢
5. 构建、部署与测试
6. 扩展与进阶
7. 总结

---

1. 引言：从Python/C#到Java与Bukkit

你可能已经习惯了Python的简洁和动态性，或者C#的强类型和.NET生态。Java在语法上与C#有诸多相似之处，因为它也深受C++影响。它是一门强类型、面向对象的语言，并且通常需要编译成字节码（.class文件）才能运行在Java虚拟机（JVM）上。

Bukkit API是Minecraft服务器插件开发的事实标准之一（虽然现在更多是使用其派生项目如Spigot、PaperMC等）。它提供了一套接口和类，允许你与Minecraft服务器进行交互，监听游戏事件，修改游戏世界，以及创建自定义功能。

我们的目标： 理解并实现一个功能，当玩家主手拿着石头按钮 (Stone Button)，副手拿着发射器 (Dispenser) 并右键时，就能持续发射箭矢，像一把机枪！箭矢的精准度会随着持续射击而降低，并且有一定几率不消耗箭矢。

---

2. 准备工作：搭建开发环境

在开始编写代码之前，我们需要设置好开发环境。

2.1 Java Development Kit (JDK)

你需要安装Java JDK，而不是JRE（Java Runtime Environment）。推荐使用OpenJDK 21或更高版本，因为Minecraft 1.21.* 通常需要较新的Java版本。

• 下载： 访问Adoptium (Eclipse Temurin) 或 Oracle JDK 官网。
• 安装： 按照安装向导指示完成安装。

2.2 集成开发环境 (IDE)

一个好的IDE能极大地提高开发效率。

• 推荐： IntelliJ IDEA Community Edition (免费且功能强大)。
• 备选： Eclipse、VS Code (配合Java插件)。

2.3 构建工具 (Maven/Gradle)

Minecraft插件项目通常使用Maven或Gradle管理依赖和构建。它们会自动下载所需的库文件，并编译你的代码。我们将以Maven为例。

• Maven： 通常集成在IDE中，无需单独安装。如果需要，也可以从Apache Maven官网下载。

2.4 Bukkit/Spigot/PaperMC 服务器

你需要一个实际的Minecraft服务器来测试你的插件。

• 下载： 访问PaperMC官网下载最新版本的paperclip.jar。
• 运行： 创建一个文件夹，将paperclip.jar放入，然后运行一次以生成eula.txt（同意EULA）和服务器文件。

---

3. 核心概念速览：Java与Bukkit特有之处

3.1 Java语言特性与Python/C#的对比

• 强类型 (Strongly Typed):
  • Python: x = 10, y = "hello" (动态类型)。
  • C#: int x = 10; string y = "hello"; (强类型)。
  • Java: int x = 10; String y = "hello"; (强类型)。变量声明时必须指定类型。
• 语句结束符:
  • Python: 换行。
  • C#/Java: ; (分号)。
• 代码块:
  • Python: 缩进。
  • C#/Java: {} (花括号)。
• 类与对象:
  • Python: class MyClass:, obj = MyClass().
  • C#: class MyClass { }, MyClass obj = new MyClass();.
  • Java: public class MyClass { }, MyClass obj = new MyClass(); (与C#非常相似，但new关键字是必须的)。
• 访问修饰符: public, private, protected, default (包级私有)。
  • Python: _name (约定私有), __name (名称修饰)。
  • C#/Java: public (公开), private (私有), protected (受保护的)。
• 接口 (Interface):
  • C#: interface IMyInterface { void DoSomething(); }.
  • Java: interface MyInterface { void doSomething(); } (与C#非常相似，类实现接口使用implements关键字)。
• 泛型 (Generics): <T> 在Java中广泛使用，类似于C#中的泛型，用于在编译时提供类型安全。
  • Map<UUID, BukkitTask>: 一个映射，键是UUID类型，值是BukkitTask类型。对应Python中的dict[uuid.UUID, Any]或C#中的Dictionary<Guid, Task>。
• Lambda表达式 (Lambda Expressions):
  • Python: lambda x: x + 1.
  • C#: x => x + 1.
  • Java: (x) -> x + 1 (在函数式接口上下文中使用，如Runnable、Consumer等)。

3.2 Bukkit API核心：事件、监听器、调度器

• 事件 (Events): Minecraft游戏中发生的任何事情，如玩家交互、方块破坏、实体生成等，都会触发一个事件。
  • PlayerInteractEvent: 玩家与方块或空气交互时触发。
  • PlayerQuitEvent: 玩家离开服务器时触发。
• 监听器 (Listeners): 你创建的类，用于“监听”并响应特定的事件。
  • 需要实现org.bukkit.event.Listener接口。
  • 事件处理方法需要用@EventHandler注解标记。
• 调度器 (Scheduler): Bukkit提供了一个任务调度系统 (BukkitScheduler)，用于在Minecraft主线程（重要的，所有与游戏对象交互都必须在主线程）或异步线程中执行任务。
  • runTaskTimer(plugin, task, delay, period): 最常用的方法之一，用于重复执行任务。
    • plugin: 你的主插件实例。
    • task: 要执行的代码（通常是Lambda表达式或Runnable实例）。
    • delay: 首次执行前的延迟（单位：游戏刻，1秒=20刻）。
    • period: 任务重复执行的周期（单位：游戏刻）。
    • 注意： Minecraft的逻辑和渲染都在一个主线程上，所以大多数Bukkit API调用必须在这个线程上进行。runTaskTimer默认就是在主线程上运行任务。
• 重要类：
  • Player: 代表一个在线玩家。
  • ItemStack: 代表一个物品堆叠。
  • Material: 代表一种方块或物品的类型（如Material.STONE_BUTTON）。
  • UUID: 玩家的唯一标识符，即使玩家改名，UUID也不会变。常用于存储与特定玩家相关的数据。
  • Vector: 3D向量，用于表示方向或速度。
  • Arrow: 箭矢实体。

3.3 项目结构：pom.xml与plugin.yml

pom.xml (Maven项目对象模型)：

这是Maven项目的配置文件，用于声明项目信息、依赖项、构建插件等。

<?xml version="1.0" encoding="UTF-8"?>
<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 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.rainyxinmain</groupId>
    <artifactId>rainyxinmain</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>jar</packaging>

    <properties>
        <maven.compiler.source>21</maven.compiler.source> <!-- 你的Java版本 -->
        <maven.compiler.target>21</maven.compiler.target> <!-- 你的Java版本 -->
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <repositories>
        <!-- SpigotMC/PaperMC 库，提供Bukkit API -->
        <repository>
            <id>papermc-repo</id>
            <url>https://repo.papermc.io/repository/maven-public/</url>
        </repository>
    </repositories>

    <dependencies>
        <!-- Bukkit/PaperMC API 依赖 -->
        <dependency>
            <groupId>io.papermc.paper</groupId>
            <artifactId>paper-api</artifactId>
            <version>1.21-R0.1-SNAPSHOT</version> <!-- 根据你的服务器版本调整 -->
            <scope>provided</scope> <!-- 插件在服务器运行时才需要此API，服务器已提供 -->
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.8.1</version>
                <configuration>
                    <source>${maven.compiler.source}</source>
                    <target>${maven.compiler.target}</target>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-shade-plugin</artifactId>
                <version>3.2.4</version>
                <executions>
                    <execution>
                        <phase>package</phase>
                        <goals>
                            <goal>shade</goal>
                        </goals>
                        <configuration>
                            <createDependencyReducedPom>false</createDependencyReducedPom>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

plugin.yml：

这是一个放置在你的插件JAR文件根目录下的YAML文件，用于告诉Minecraft服务器你的插件叫什么、作者是谁、主类在哪里等信息。

name: RainyXinMain
version: 1.0-SNAPSHOT
main: com.rainyxinmain.rainyxinmain.RainyxinMAIN # 你的主插件类路径
api-version: 1.21 # 你的服务器API版本
authors: [RainyXin]
description: A custom plugin with various features.
permissions: # 插件需要的权限
  rainyxinmain.feature.continuousarrow:
    description: Allows players to use the continuous arrow firing feature.
    default: op # 默认只给OP（操作员）

请确保你的主插件类（RainyxinMAIN）继承自org.bukkit.plugin.java.JavaPlugin，并且在onEnable()方法中注册事件监听器：

// 这是你的主插件类 RainyxinMAIN.java 的简化示例
package com.rainyxinmain.rainyxinmain;

import com.rainyxinmain.rainyxinmain.features.ContinuousArrowFireListener;
import org.bukkit.plugin.java.JavaPlugin;

public final class RainyxinMAIN extends JavaPlugin {

    @Override
    public void onEnable() {
        // 当插件启动时，注册事件监听器
        getServer().getPluginManager().registerEvents(new ContinuousArrowFireListener(this), this);
        getLogger().info("RainyXinMain has been enabled!");
    }

    @Override
    public void onDisable() {
        // 当插件关闭时执行的清理工作 (可选)
        getLogger().info("RainyXinMain has been disabled!");
    }
}

---

4. 代码深度解析：箭矢机枪功能实现

现在，我们来逐行解析你提供的ContinuousArrowFireListener.java代码。

package com.rainyxinmain.rainyxinmain.features;

import com.rainyxinmain.rainyxinmain.RainyxinMAIN; // 导入主插件类
import org.bukkit.Bukkit; // 导入Bukkit主类，用于访问调度器等
import org.bukkit.Material; // 导入Material枚举，表示物品类型
import org.bukkit.entity.Arrow; // 导入Arrow实体类
import org.bukkit.entity.Player; // 导入Player实体类
import org.bukkit.event.EventHandler; // 导入EventHandler注解
import org.bukkit.event.Listener; // 导入Listener接口
import org.bukkit.event.block.Action; // 导入Action枚举，表示交互动作
import org.bukkit.event.player.PlayerInteractEvent; // 导入玩家交互事件
import org.bukkit.event.player.PlayerItemHeldEvent; // 导入玩家手持物品改变事件
import org.bukkit.event.player.PlayerQuitEvent; // 导入玩家退出事件
import org.bukkit.event.player.PlayerSwapHandItemsEvent; // 导入玩家交换主副手物品事件
import org.bukkit.inventory.ItemStack; // 导入ItemStack类，表示物品堆叠
import org.bukkit.scheduler.BukkitTask; // 导入BukkitTask类，表示调度器任务
import org.bukkit.util.Vector; // 导入Vector类，表示3D向量

import java.util.HashMap; // 导入HashMap，用于存储键值对
import java.util.Map; // 导入Map接口
import java.util.UUID; // 导入UUID类
import org.bukkit.Sound; // 导入Sound枚举，用于播放声音
import java.util.Random; // 导入Random类，用于生成随机数

public class ContinuousArrowFireListener implements Listener {
    // 这行定义了一个公共类，名为ContinuousArrowFireListener，并声明它实现了Listener接口。
    // 实现了Listener接口的类才能被Bukkit的事件系统识别为事件监听器。
    // 类似于C#中实现某个接口：public class MyListener : IMyListener

    private final RainyxinMAIN plugin; // 存储主插件实例的引用，final表示其在初始化后不能被修改。
    private final Map<UUID, BukkitTask> activeFiringTasks; // 一个Map，用于存储正在射击的玩家(UUID)及其对应的BukkitTask。
                                                        // 类似于Python的字典 {UUID: Task} 或 C#的 Dictionary<Guid, Task>。
    private final Map<UUID, Long> firingStartTime; // 存储玩家开始持续射击的时间戳，用于计算箭矢扩散。
    private final Random random; // 用于生成随机数，例如箭矢消耗的概率。
    private final Map<UUID, ItemStack> cachedArrowStacks; // 缓存玩家当前使用的箭矢堆叠，避免重复查找。

    public ContinuousArrowFireListener(RainyxinMAIN plugin) {
        // 构造函数，在创建这个类的实例时被调用。
        // 它接收一个RainyxinMAIN类型的参数，即你的主插件实例。
        this.plugin = plugin; // 将传入的插件实例赋值给类的成员变量。
        this.activeFiringTasks = new HashMap<>(); // 初始化HashMap，空字典/哈希表。
        this.firingStartTime = new HashMap<>(); // 初始化HashMap。
        this.random = new Random(); // 初始化随机数生成器。
        this.cachedArrowStacks = new HashMap<>(); // 初始化HashMap。
    }

    @EventHandler // @EventHandler注解表示这个方法是一个事件处理器，它将监听PlayerInteractEvent事件。
                  // 类似于Python的装饰器 @event_handler 或 C#的特性 [EventHandler]。
    public void onPlayerInteract(PlayerInteractEvent event) {
        Player player = event.getPlayer(); // 获取触发事件的玩家实例。
        Action action = event.getAction(); // 获取玩家的交互动作（右键、左键等）。

        // 只在右键交互时触发 (右键空气或右键方块)
        if (action != Action.RIGHT_CLICK_AIR && action != Action.RIGHT_CLICK_BLOCK) {
            return; // 如果不是右键，则直接返回，不执行后续代码。
        }

        // 检查玩家是否拥有特定权限
        if (!player.hasPermission("rainyxinmain.feature.continuousarrow")) {
            return; // 如果玩家没有权限，则返回。
        }

        // 检查玩家是否手持正确的物品
        ItemStack mainHand = player.getInventory().getItemInMainHand(); // 获取主手物品堆叠。
        ItemStack offHand = player.getInventory().getItemInOffHand();   // 获取副手物品堆叠。

        // 检查主手是否是石头按钮，副手是否是发射器
        boolean hasRequiredItems = mainHand.getType() == Material.STONE_BUTTON && offHand.getType() == Material.DISPENSER;

        if (hasRequiredItems) {
            // 如果该玩家已经有射击任务在运行，则不做任何事情，避免重复启动。
            if (activeFiringTasks.containsKey(player.getUniqueId())) {
                return;
            }
            // 缓存玩家当前背包中的箭矢堆叠，避免每次射击都重新查找。
            // 稍后会解释findArrowInInventory方法。
            cachedArrowStacks.put(player.getUniqueId(), findArrowInInventory(player));

            // 为该玩家启动一个新的持续射击任务。
            firingStartTime.put(player.getUniqueId(), System.currentTimeMillis()); // 记录开始时间（毫秒）。

            // Bukkit调度器：runTaskTimer 方法用于在指定延迟后，以指定周期重复执行一个任务。
            // plugin: 插件实例，指示任务属于哪个插件。
            // () -> { ... }: 这是一个Java Lambda表达式，代表一个匿名函数/可运行的任务。
            // 0L: 首次执行的延迟（0刻，即立即执行）。L表示是long类型。
            // 1L: 任务重复的周期（1刻，即每游戏刻执行一次，Minecraft每秒20刻）。
            BukkitTask task = Bukkit.getScheduler().runTaskTimer(plugin, () -> {
                // 这个Lambda表达式中的代码会在每游戏刻被执行。

                // 检查玩家是否仍然在线。如果下线了，停止任务。
                if (!player.isOnline()) {
                    stopFiringTask(player.getUniqueId());
                    return;
                }

                // 再次检查玩家是否仍然手持正确的物品。
                ItemStack currentMainHand = player.getInventory().getItemInMainHand();
                ItemStack currentOffHand = player.getInventory().getItemInOffHand();
                boolean currentHasRequiredItems = currentMainHand.getType() == Material.STONE_BUTTON && currentOffHand.getType() == Material.DISPENSER;
                if (!currentHasRequiredItems) {
                    stopFiringTask(player.getUniqueId()); // 如果物品不对，停止任务。
                    return;
                }

                ItemStack arrowStack = cachedArrowStacks.get(player.getUniqueId());

                // 如果缓存的箭矢堆叠为空或数量为0，则重新查找玩家背包。
                if (arrowStack == null || arrowStack.getAmount() == 0) {
                    arrowStack = findArrowInInventory(player);
                    cachedArrowStacks.put(player.getUniqueId(), arrowStack); // 更新缓存
                    if (arrowStack == null) {
                        stopFiringTask(player.getUniqueId()); // 如果找不到箭矢，停止任务。
                        return;
                    }
                }

                // 再次确保箭矢堆叠不为空且数量大于0，这是一个健壮性检查。
                if (arrowStack.getAmount() <= 0) {
                    stopFiringTask(player.getUniqueId());
                    return;
                }

                // 箭矢消耗逻辑：50% 几率不消耗箭矢。
                if (random.nextDouble() < 0.5) {
                    // 不消耗箭矢
                } else {
                    arrowStack.setAmount(arrowStack.getAmount() - 1); // 消耗一支箭矢。
                }

                // 在玩家眼睛位置发射箭矢，初始速度方向是玩家的视角方向，乘以6.0表示速度大小。
                Arrow arrow = player.launchProjectile(Arrow.class, player.getEyeLocation().getDirection().multiply(6.0));

                // 箭矢扩散逻辑：根据持续射击时间增加扩散度。
                long timeElapsed = System.currentTimeMillis() - firingStartTime.getOrDefault(player.getUniqueId(), System.currentTimeMillis());
                // timeElapsed: 持续射击的时间，单位毫秒。
                // getOrDefault: 如果找不到玩家的开始时间，则使用当前时间，避免空指针。

                // 最大扩散角度（弧度），例如0.5弧度约等于28度。
                double maxSpread = 0.5;
                // 扩散因子：将持续时间归一化到0-1之间，例如5秒（5000毫秒）达到最大扩散。
                double spreadFactor = Math.min(1.0, timeElapsed / 5000.0);
                // 当前扩散量：最大扩散乘以扩散因子。
                double currentSpread = maxSpread * spreadFactor;

                // 获取玩家的基础视角方向。
                Vector baseDirection = player.getLocation().getDirection();

                // 应用随机扩散：通过在基础方向上添加小的随机偏移量来模拟扩散。
                // random.nextDouble() - 0.5: 生成-0.5到0.5之间的随机数。
                // 乘以currentSpread来控制扩散的强度。
                double randomX = (random.nextDouble() - 0.5) * currentSpread;
                double randomY = (random.nextDouble() - 0.5) * currentSpread;
                double randomZ = (random.nextDouble() - 0.5) * currentSpread;

                // 克隆基础方向，然后加上随机偏移量，最后归一化以保持方向向量的单位长度。
                Vector spreadDirection = baseDirection.clone().add(new Vector(randomX, randomY, randomZ)).normalize();
                // 将新的扩散方向应用于箭矢的速度，速度大小保持不变。
                arrow.setVelocity(spreadDirection.multiply(6.0));

                arrow.setShooter(player); // 设置箭矢的射击者为玩家，这样箭矢的击中事件可以追溯到玩家。

                // 播放射击音效。
                player.playSound(player.getLocation(), Sound.ENTITY_ARROW_SHOOT, 1.0F, 1.0F);
            }, 0L, 1L); // 0L延迟，1L周期，即每刻都执行。
            activeFiringTasks.put(player.getUniqueId(), task); // 将任务存储到Map中，以便后续停止。
        } else {
            // 如果玩家不再手持正确的物品，停止任何正在进行的射击任务。
            stopFiringTask(player.getUniqueId());
        }
    }

    @EventHandler
    public void onPlayerItemHeld(PlayerItemHeldEvent event) {
        // 如果玩家切换了主手物品，停止射击任务。
        stopFiringTask(event.getPlayer().getUniqueId());
    }

    @EventHandler
    public void onPlayerSwapHandItems(PlayerSwapHandItemsEvent event) {
        // 如果玩家交换了主副手物品，停止射击任务。
        stopFiringTask(event.getPlayer().getUniqueId());
    }

    @EventHandler
    public void onPlayerQuit(PlayerQuitEvent event) {
        // 如果玩家退出服务器，停止射击任务，进行清理。
        stopFiringTask(event.getPlayer().getUniqueId());
    }

    private void stopFiringTask(UUID playerId) {
        // 这是一个私有辅助方法，用于停止指定玩家的射击任务并清理相关数据。
        BukkitTask task = activeFiringTasks.remove(playerId); // 从Map中移除并获取任务实例。
        firingStartTime.remove(playerId); // 移除开始时间。
        cachedArrowStacks.remove(playerId); // 移除缓存的箭矢堆叠。
        if (task != null) {
            task.cancel(); // 如果任务存在，取消它，停止重复执行。
        }
    }

    private ItemStack findArrowInInventory(Player player) {
        // 这是一个私有辅助方法，用于在玩家背包中查找箭矢。

        // 优先在快捷栏 (hotbar) 中查找箭矢 (索引 0-8)。
        for (int i = 0; i < 9; i++) {
            ItemStack item = player.getInventory().getItem(i);
            if (item != null && item.getType() == Material.ARROW) {
                return item; // 找到即返回。
            }
        }

        // 如果快捷栏没有，则检查背包的其他部分。
        for (ItemStack item : player.getInventory().getContents()) {
            if (item != null && item.getType() == Material.ARROW) {
                return item; // 找到即返回。
            }
        }
        return null; // 如果整个背包都找不到箭矢，则返回null。
    }
}

4.1 类定义与构造函数

• public class ContinuousArrowFireListener implements Listener:
  • public: 公共访问修饰符，意味着这个类可以在任何地方被访问。
  • class: 定义一个类。
  • implements Listener: Java中，一个类可以实现一个或多个接口。Listener是一个Bukkit API接口，实现它表明这个类可以作为事件监听器。
  • Python/C#对比: 类似于C#的 public class MyListener : IListener 或 Python中定义一个类，然后由框架在内部注册其带有特定装饰器的方法。
• 成员变量:
  • private final RainyxinMAIN plugin;: private表示私有，只能在类内部访问。final表示这个变量一旦被赋值就不能再改变。RainyxinMAIN是你的主插件类，通过它我们可以访问插件的配置、日志等。
  • private final Map<UUID, BukkitTask> activeFiringTasks;: 使用Map（在Java中是HashMap的接口）来存储每个玩家对应的射击任务。键是UUID（玩家的唯一ID），值是BukkitTask（Bukkit调度器返回的任务对象）。这样，我们可以方便地根据玩家ID查找并取消他们的射击任务。
  • Python/C#对比: 类似于Python的 self.active_firing_tasks = {} 或 C#的 private readonly Dictionary<Guid, Task> activeFiringTasks = new Dictionary<Guid, Task>();。
• 构造函数 public ContinuousArrowFireListener(RainyxinMAIN plugin):
  • 这是创建ContinuousArrowFireListener对象时执行的代码。它接收主插件的实例作为参数，并将其保存到this.plugin。
  • 在构造函数中，所有HashMap都被初始化为空。

4.2 onPlayerInteract：玩家交互事件监听

• @EventHandler: 这个注解告诉Bukkit的事件系统，onPlayerInteract方法是一个事件处理程序。当PlayerInteractEvent事件发生时，Bukkit会自动调用这个方法。
• event.getPlayer(): 获取触发事件的Player对象，代表了游戏中的玩家。
• event.getAction(): 获取玩家的交互动作，我们只关心RIGHT_CLICK_AIR（右键空气）和RIGHT_CLICK_BLOCK（右键方块）。
• 权限检查 player.hasPermission("rainyxinmain.feature.continuousarrow"): 这是一个很好的实践，只允许拥有特定权限的玩家使用此功能。插件的plugin.yml中需要定义这个权限。
• 物品检查:
  • player.getInventory().getItemInMainHand() 和 player.getInventory().getItemInOffHand()：分别获取玩家主手和副手持有的ItemStack。
  • mainHand.getType() == Material.STONE_BUTTON 和 offHand.getType() == Material.DISPENSER: 检查物品的类型是否符合要求。Material是一个枚举，包含了Minecraft中所有物品和方块的类型。

4.3 核心：Bukkit调度器与持续射击任务

• activeFiringTasks.containsKey(player.getUniqueId()): 在启动新任务之前，检查玩家是否已经有一个活跃的射击任务。这可以防止玩家多次右键时启动多个重复的任务。
• firingStartTime.put(player.getUniqueId(), System.currentTimeMillis());: 记录玩家开始射击的当前系统时间（毫秒）。这用于后续计算射击的持续时间，从而影响箭矢的扩散。
• BukkitTask task = Bukkit.getScheduler().runTaskTimer(plugin, () -> { ... }, 0L, 1L);: 这是实现持续射击的核心。
  • Bukkit.getScheduler(): 获取Bukkit的调度器实例。
  • runTaskTimer(...): 计划一个重复执行的任务。
    • plugin: 你的主插件实例，告诉Bukkit这个任务属于哪个插件。
    • () -> { ... }: 这是一个Lambda表达式，它定义了任务在每次执行时要运行的代码块。在Java中，这通常用于实现Runnable接口，类似于Python的匿名函数或C#的匿名方法/Lambda表达式。
    • 0L: 第一次执行任务前的延迟（0个游戏刻）。L表示这是一个long类型的值。
    • 1L: 任务重复的周期（每1个游戏刻执行一次）。Minecraft每秒有20个游戏刻，所以这意味着每0.05秒发射一支箭矢，实现了“机枪”的效果。
  • Lambda内部逻辑:
    • 在线检查和物品检查: 每刻都再次检查玩家是否在线，以及是否仍然手持正确的物品。如果条件不再满足，就调用stopFiringTask停止任务。这是保持任务健壮性和响应性的关键。
    • 箭矢查找与缓存: cachedArrowStacks.get(player.getUniqueId())尝试获取缓存的箭矢。如果缓存为空或箭矢用完，会调用findArrowInInventory重新查找。这样做可以减少频繁遍历玩家背包的开销。
    • 箭矢消耗: arrowStack.setAmount(arrowStack.getAmount() - 1); 将箭矢数量减少1。
    • random.nextDouble() < 0.5: random.nextDouble()生成一个0.0到1.0之间的随机浮点数。如果小于0.5（即有50%的几率），就不消耗箭矢。
• activeFiringTasks.put(player.getUniqueId(), task);: 将新创建的任务对象存储在activeFiringTasks Map中，以玩家的UUID作为键。这样，我们就可以在玩家改变物品或退出时，通过UUID找到并取消这个任务。

4.4 箭矢生成、消耗与扩散逻辑

• Arrow arrow = player.launchProjectile(Arrow.class, player.getEyeLocation().getDirection().multiply(6.0));:
  • player.launchProjectile(Arrow.class, ...): Bukkit提供的方法，用于在玩家位置发射一个指定类型的投掷物。Arrow.class指定了投掷物是箭矢。
  • player.getEyeLocation().getDirection(): 获取玩家视角的方向向量。
  • .multiply(6.0): 将方向向量乘以6.0，设置箭矢的初始速度大小。
• 箭矢扩散 spread 逻辑: 这是这个功能的一个亮点，模拟了机枪射击越久越不准的效果。
  • long timeElapsed = System.currentTimeMillis() - firingStartTime.getOrDefault(player.getUniqueId(), System.currentTimeMillis());: 计算从开始射击到当前时间经过了多少毫秒。getOrDefault是为了防止firingStartTime中没有该玩家的记录（虽然理论上不会发生）。
  • double maxSpread = 0.5;: 定义了最大的扩散角度（单位是弧度）。可以调整这个值来控制扩散程度。
  • double spreadFactor = Math.min(1.0, timeElapsed / 5000.0);: 计算扩散因子。将timeElapsed除以5000.0（5秒），并用Math.min(1.0, ...)确保因子不会超过1.0。这意味着在持续射击5秒后，扩散达到最大。
  • double currentSpread = maxSpread * spreadFactor;: 实际的扩散量，随着时间逐渐增大。
  • Vector baseDirection = player.getLocation().getDirection();: 获取玩家当前的朝向。
  • randomX/Y/Z: 通过在-0.5 * currentSpread到0.5 * currentSpread之间生成随机数，来为箭矢的飞行方向添加随机扰动。
  • baseDirection.clone().add(new Vector(randomX, randomY, randomZ)).normalize();:
    • .clone(): 创建baseDirection的副本，避免修改原始的玩家方向。
    • .add(new Vector(...)): 将随机偏移量加到基础方向上。
    • .normalize(): 将结果向量归一化，使其长度为1，只保留方向信息。
  • arrow.setVelocity(spreadDirection.multiply(6.0));: 将计算出的带有扩散的spreadDirection应用到箭矢的速度上，速度大小保持不变。
• arrow.setShooter(player);: 这很重要！它将玩家设置为箭矢的射击者。这意味着如果箭矢击中生物，游戏会认为是由该玩家造成的伤害，并且其他插件（如领地插件）也可以正确识别箭矢来源。
• player.playSound(...): 播放一个射击音效。Sound.ENTITY_ARROW_SHOOT是Bukkit提供的内置音效。参数分别是位置、音量和音高。

4.5 停止射击的条件与清理

为了确保资源被正确释放，并且功能在玩家不再符合条件时停止，有几个事件处理器来处理停止射击的逻辑：

• onPlayerItemHeld(PlayerItemHeldEvent event): 当玩家切换快捷栏物品时触发。如果玩家切换了手持物品，机枪就应该停止射击。
• onPlayerSwapHandItems(PlayerSwapHandItemsEvent event): 当玩家使用快捷键交换主副手物品时触发。
• onPlayerQuit(PlayerQuitEvent event): 当玩家退出服务器时触发。必须停止任务，否则可能会导致内存泄漏或其他问题。
• private void stopFiringTask(UUID playerId):
  • 这是一个私有辅助方法，用于集中处理停止任务的逻辑。
  • activeFiringTasks.remove(playerId): 从Map中移除玩家对应的任务。
  • firingStartTime.remove(playerId) 和 cachedArrowStacks.remove(playerId): 清理与该玩家相关的其他缓存数据。
  • task.cancel(): 关键一步。调用BukkitTask的cancel()方法会停止由runTaskTimer创建的重复任务，防止它继续执行。

4.6 辅助方法：查找箭矢

• private ItemStack findArrowInInventory(Player player):
  • 这个方法用于在玩家的背包中查找箭矢。
  • 优先检查快捷栏: for (int i = 0; i < 9; i++) 循环检查玩家背包的前9个槽位（即快捷栏）。
  • 检查整个背包: 如果快捷栏没有找到，再遍历player.getInventory().getContents()检查所有背包槽位。
  • item != null && item.getType() == Material.ARROW: 检查槽位是否有物品，并且物品类型是否是箭矢。

---

5. 构建、部署与测试

1. 项目创建 (IntelliJ IDEA):

   • 打开IntelliJ IDEA。
   • 选择 New Project。
   • 选择 Maven。
   • 选择 Create from Archetype，然后点击 Add Archetype。
     • GroupId: org.bukkit
     • ArtifactId: bukkit-archetype
     • Version: 1.0.1-SNAPSHOT (或者更高的稳定版本)
   • 填写 GroupId (如 com.rainyxinmain), ArtifactId (如 rainyxinmain)。
   • 完成项目创建向导。
   • 手动配置: 很多时候，直接使用Maven Archetype可能会引入旧版本的Bukkit或不适用于PaperMC。更常见的方式是：
     • 创建新的Maven项目。
     • 手动添加上述3.3节中的pom.xml内容。
     • 创建你的主插件类 (RainyxinMAIN.java)，继承JavaPlugin。
     • 创建 resources 文件夹并在其中创建 plugin.yml 文件。

2. 集成代码:

   • 将ContinuousArrowFireListener.java文件放到正确的包路径下（例如：src/main/java/com/rainyxinmain/rainyxinmain/features/）。
   • 确保你的主插件类 RainyxinMAIN.java 中，在 onEnable() 方法内注册了监听器：

     // ... 在 RainyxinMAIN.java 中
     @Override
     public void onEnable() {
         // 注册 ContinuousArrowFireListener
         getServer().getPluginManager().registerEvents(new ContinuousArrowFireListener(this), this);
         getLogger().info("RainyXinMain features are enabled!");
     }
     // ...
     

3. 构建插件:

   • 在IntelliJ IDEA中，打开Maven工具窗口 (通常在右侧)。
   • 在 rainyxinmain -> Lifecycle 下，双击 clean，然后双击 package。
   • Maven会下载依赖、编译代码，并生成一个JAR文件（通常在 target/ 目录下，名为 rainyxinmain-1.0-SNAPSHOT.jar）。

4. 部署到服务器:

   • 将生成的JAR文件复制到你的Minecraft服务器根目录下的 plugins 文件夹中。
   • 启动或重启你的Minecraft服务器。

5. 测试功能:

   • 进入游戏，成为OP (/op <你的ID>)。
   • 给予自己权限 (/lp user <你的ID> permission set rainyxinmain.feature.continuousarrow true)。
   • 通过命令获取物品：
     • /give @s stone_button
     • /give @s dispenser
     • /give @s arrow 64
   • 主手持有石头按钮，副手持有发射器。
   • 右键！你应该能看到箭矢像机枪一样发射出来，并且随着射击时间的增加，箭矢会越来越散。
   • 尝试切换手持物品或退出游戏，检查机枪是否停止射击。

---

6. 扩展与进阶

• 配置化: 将物品类型、射速、扩散参数、箭矢消耗几率等变量写入插件的配置文件 (config.yml)，允许服务器管理员自定义。
• 不同物品组合: 允许更多物品组合来触发不同的射击模式（例如，使用弓+TNT可以发射爆炸箭）。
• 冷却时间: 添加射击冷却时间，防止过于频繁的启动。
• 效果与粒子: 在射击时添加粒子效果或更多音效。
• 自定义箭矢: 为发射的箭矢添加自定义属性，例如火焰箭、毒箭等。
• 动画: 模拟发射器的发射动画。
• 重构: 将箭矢消耗、扩散计算等逻辑封装到单独的辅助类中，使代码更模块化。
• CommandAPI/PaperAPI: 学习使用更高级的API，如PaperMC提供的额外API，或者CommandAPI简化命令创建。
• 数据库集成: 存储玩家的自定义设置或统计数据。

---

7. 总结

通过这个“手持发射器箭矢机枪”的例子，你已经：

• 了解了Java语言与Python/C#的相似点和不同点。
• 掌握了Bukkit事件、监听器和调度器的核心概念。
• 学会了如何设置Maven项目和plugin.yml。
• 亲手分析并理解了一个实际的Minecraft插件功能代码。
• 实践了插件的构建、部署和测试。

---

Bukkit API 常用方法列表：箭矢机枪及类似功能

核心 Bukkit API 组件与概念

• org.bukkit.plugin.java.JavaPlugin:

  • 你的主插件类必须继承这个类。
  • onEnable(): 插件启动时调用，通常用于注册事件监听器、加载配置等。
  • onDisable(): 插件关闭时调用，通常用于保存数据、取消任务等。
  • getLogger(): 获取插件的Logger实例，用于输出日志信息。
  • getServer(): 获取 org.bukkit.Server 实例，提供访问服务器的各种功能，如获取玩家列表、调度器等。

• org.bukkit.event.Listener:

  • 一个空接口，表示一个类是一个事件监听器。任何想监听Bukkit事件的类都必须实现它。

• @org.bukkit.event.EventHandler:

  • 注解，标记方法为事件处理程序。当特定事件发生时，Bukkit会自动调用此方法。
  • 可以通过参数设置事件处理的优先级（priority）和是否忽略已取消的事件（ignoreCancelled）。

• org.bukkit.scheduler.BukkitScheduler:

  • 通过 Bukkit.getScheduler() 或 plugin.getServer().getScheduler() 获取。
  • runTask(Plugin plugin, Runnable task): 在下一个服务器刻（主线程）执行一次任务。
  • runTaskLater(Plugin plugin, Runnable task, long delay): 在指定延迟后（主线程）执行一次任务。
    • delay: 延迟的游戏刻数 (20刻 = 1秒)。
  • runTaskTimer(Plugin plugin, Runnable task, long delay, long period): 在指定延迟后开始，然后每隔指定周期（主线程）重复执行任务。
    • period: 重复执行的周期游戏刻数。
  • runTaskAsynchronously(Plugin plugin, Runnable task): 在一个新线程中执行一次异步任务。
    • 注意： 大多数Bukkit API调用都不是线程安全的，必须在主线程执行。异步任务通常用于耗时计算，然后通过 runTask() 回到主线程执行Bukkit API调用。
  • org.bukkit.scheduler.BukkitTask:
    • cancel(): 取消一个正在运行或等待执行的调度器任务。这对于停止重复任务（如机枪射击）至关重要。

玩家 (org.bukkit.entity.Player) 相关

• getPlayer(): (在 PlayerEvent 中使用) 获取触发事件的玩家实例。
• getUniqueId(): 获取玩家的唯一标识符（UUID）。推荐使用UUID来识别玩家，而不是名字，因为名字可以改变。
• isOnline(): 检查玩家是否在线。
• hasPermission(String permission): 检查玩家是否拥有某个权限。
• getLocation(): 获取玩家当前的脚部位置 (org.bukkit.Location)。
• getEyeLocation(): 获取玩家的眼睛位置 (org.bukkit.Location)，通常用于射击或视觉效果的起点。
• getDirection(): (在 Location 中使用) 获取玩家当前朝向的单位向量 (org.bukkit.util.Vector)。
• sendMessage(String message): 向玩家发送一条聊天消息。
• sendActionBar(String message): 在玩家屏幕的Action Bar（血条上方）显示一条消息。
• playSound(Location location, Sound sound, float volume, float pitch): 在玩家附近播放一个声音。
• launchProjectile(Class<? extends Projectile> projectileClass, Vector velocity): 发射一个投掷物（如箭矢、雪球、火焰弹等）。
  • projectileClass: 要发射的投掷物类型，如 Arrow.class, Fireball.class。
  • velocity: 投掷物的初始速度向量。

物品与背包 (org.bukkit.inventory.*) 相关

• org.bukkit.inventory.PlayerInventory: 玩家背包。

  • getItemInMainHand(): 获取玩家主手持有的物品 (org.bukkit.inventory.ItemStack)。
  • getItemInOffHand(): 获取玩家副手持有的物品 (org.bukkit.inventory.ItemStack)。
  • getItem(int slot): 获取指定槽位索引的物品。
  • getContents(): 获取背包中所有物品的数组。
  • addItem(ItemStack... items): 向背包添加物品。
  • removeItem(ItemStack... items): 从背包移除物品。
  • contains(Material material): 检查背包是否包含某种类型的物品。
  • clear(int slot): 清空指定槽位的物品。
  • clear(): 清空整个背包。

• org.bukkit.inventory.ItemStack: 物品堆叠。

  • getType(): 获取物品的材质类型 (org.bukkit.Material)。
  • getAmount(): 获取物品堆叠的数量。
  • setAmount(int amount): 设置物品堆叠的数量。
  • hasItemMeta(): 检查物品是否有自定义的元数据（如名称、附魔、Lore）。
  • getItemMeta(): 获取物品的元数据 (org.bukkit.inventory.meta.ItemMeta)。
  • clone(): 创建物品堆叠的副本。

• org.bukkit.Material:

  • 一个枚举，代表Minecraft中所有方块和物品的类型。
  • 示例：Material.STONE_BUTTON, Material.DISPENSER, Material.ARROW.

• org.bukkit.inventory.meta.ItemMeta:

  • setDisplayName(String name): 设置物品的显示名称（支持颜色代码）。
  • setLore(List<String> lore): 设置物品的Lore（描述文字）。
  • addEnchant(Enchantment ench, int level, boolean ignoreLevelRestriction): 为物品添加附魔。
  • isUnbreakable(): 检查物品是否不可破坏。
  • setUnbreakable(boolean unbreakable): 设置物品是否不可破坏。

实体 (org.bukkit.entity.*) 相关

• org.bukkit.entity.Arrow: 箭矢实体。

  • setShooter(LivingEntity shooter): 设置箭矢的射击者（通常是玩家）。这对于伤害归属和插件兼容性很重要。
  • setVelocity(Vector vector): 设置实体（包括箭矢）的运动速度和方向。
  • isCritical() / setCritical(boolean critical): 检查/设置箭矢是否为暴击箭。
  • setDamage(double damage): 设置箭矢造成的伤害。

• org.bukkit.entity.Projectile: 投掷物接口，Arrow 的父接口。

  • getShooter(): 获取投掷物的射击者。

• org.bukkit.entity.Entity: 所有实体的基接口。

  • getLocation(): 获取实体当前的位置。
  • remove(): 从世界中移除实体。
  • getType(): 获取实体的类型 (org.bukkit.entity.EntityType)。
  • getUniqueId(): 获取实体的唯一标识符。

• org.bukkit.entity.LivingEntity: 所有有生命实体的基接口（如玩家、怪物）。

  • setHealth(double health): 设置实体的生命值。
  • damage(double amount): 对实体造成伤害。

位置与向量 (org.bukkit.Location, org.bukkit.util.Vector) 相关

• org.bukkit.Location: 表示Minecraft世界中的一个三维坐标点，以及可选的朝向信息（yaw, pitch）。

  • getX(), getY(), getZ(): 获取坐标。
  • getWorld(): 获取该位置所属的世界。
  • getBlock(): 获取该位置处的方块。
  • add(Vector vector) / subtract(Vector vector): 移动位置。
  • toVector(): 将Location转换为Vector。

• org.bukkit.util.Vector: 表示一个三维向量，用于方向、速度或相对位置。

  • getX(), getY(), getZ(): 获取分量。
  • add(Vector other): 向量加法。
  • subtract(Vector other): 向量减法。
  • multiply(double scalar): 向量与标量相乘。
  • normalize(): 将向量归一化为单位向量（长度为1），只保留方向。
  • length(): 获取向量的长度。
  • clone(): 创建向量的副本。在修改向量时，如果不想影响原始向量，应先克隆。
  • rotateAroundX/Y/Z(double angle): 绕X/Y/Z轴旋转向量。

世界 (org.bukkit.World) 相关

• 通过 player.getWorld() 或 Bukkit.getWorld(String name) 获取。
• spawnEntity(Location location, EntityType type): 在指定位置生成一个实体。
• spawnParticle(Particle particle, Location location, int count, double offsetX, double offsetY, double offsetZ, double extra): 在指定位置生成粒子效果。
• getBlockAt(Location location): 获取指定位置的方块。
• getNearbyEntities(Location location, double x, double y, double z): 获取以指定位置为中心，指定半径内的所有实体。

---

通过熟练运用这些方法，你将能够创建各种复杂的Minecraft服务器插件功能，无论是物品交互、自定义技能，还是世界改造！