Player WorldBorder API - 玩家世界边界接口

BorderAPI 是一款允许为每位玩家单独定义世界边界的 API 插件，为服务器提供了高度灵活的世界边界管理能力。

💡版本发布

版本更新会首先在 GitHub Releases 发布，因为这里实现了近乎自动化的发布流程。目前 Spigotmc 暂不支持自动创建发布。

• 如果你需要比最新次要版本更早的版本，可以在此处找到：https://github.com/yannicklamprecht/WorldBorderAPI/releases

版本号规则

版本号遵循 Minecraft 版本 -> 插件版本的映射规则。

• 格式：1.<mcversion> -> 1.<mcversion without dots>.<fix version>
• 例如：

- 1.19.3 -> 1.193.0

- 1.20.2 -> 1.202.0

- 1.20.4 -> 1.204.0

🔧使用方法

开发者若想使用此 API，请参阅详细的使用文档：https://github.com/yannicklamprecht/WorldBorderAPI/blob/main/how-to-use.md

❓旧版本支持

对于旧版本的支持情况，请查看此概览页面：https://github.com/yannicklamprecht/WorldBorderAPI/blob/main/legacy.md

---

插件作者：~ysl3000

如何使用 WorldBorderAPI

WorldBorderAPI 是一个用于管理 Minecraft 世界边界的强大 API。它允许你为世界设置圆形或矩形的边界，并自定义玩家在边界处的行为，例如传送或显示消息。本指南将帮助你了解如何将其集成到你的插件中。

💡快速开始

要开始使用 WorldBorderAPI，你需要将其作为依赖项添加到你的项目中。

添加为 Maven 依赖

在你的 pom.xml 文件中添加以下仓库和依赖项：

<repositories>
    <repository>
        <id>yannicklamprecht</id>
        <url>https://repo.yannicklamprecht.de/repository/maven-public/</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>de.iani</groupId>
        <artifactId>WorldBorderAPI</artifactId>
        <version>2.0.0</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

添加为 Gradle 依赖

在你的 build.gradle 文件中添加以下内容：

repositories {
    maven {
        url "https://repo.yannicklamprecht.de/repository/maven-public/"
    }
}

dependencies {
    compileOnly 'de.iani:WorldBorderAPI:2.0.0'
}

🎮基础用法

获取 API 实例是使用 WorldBorderAPI 的第一步。

获取 API 实例

在你的主类中，通过 ServicesManager 获取 WorldBorderAPI 实例：

WorldBorderAPI api = Bukkit.getServicesManager().load(WorldBorderAPI.class);
if (api == null) {
    // 处理 API 不可用的情况（例如，WorldBorder 插件未安装）
    getLogger().severe("WorldBorderAPI 未找到！请确保 WorldBorder 插件已安装。");
    Bukkit.getPluginManager().disablePlugin(this);
    return;
}

🔧核心功能

API 提供了多种方法来创建和管理世界边界。

创建边界

你可以为世界创建两种形状的边界：圆形或矩形。

• 创建圆形边界：使用 createBorder 方法并指定中心点和半径。

    // 在世界的 (0, 0) 处创建一个半径为 1000 的圆形边界
    api.createBorder(world, BorderShape.CIRCLE, new Position2D(0, 0), 1000);

• 创建矩形边界：使用 createBorder 方法并指定两个对角点。

    // 创建一个从 (-500, -500) 到 (500, 500) 的矩形边界
    api.createBorder(world, BorderShape.SQUARE, new Position2D(-500, -500), new Position2D(500, 500));

检查位置是否在边界内

使用 isInsideBorder 方法可以检查一个给定的位置是否在指定世界的边界内。

Location location = player.getLocation();
boolean inside = api.isInsideBorder(location.getWorld(), new Position2D(location.getX(), location.getZ()));
if (!inside) {
    player.sendMessage("你已超出世界边界！");
}

获取边界信息

你可以查询世界的边界形状和参数。

• 获取边界形状：使用 getBorderShape 方法。

    BorderShape shape = api.getBorderShape(world);

• 获取圆形边界参数：如果边界是圆形的，可以获取其中心和半径。

    if (shape == BorderShape.CIRCLE) {
        Position2D center = api.getCenter(world);
        double radius = api.getRadius(world);
    }

• 获取矩形边界参数：如果边界是矩形的，可以获取其最小和最大坐标点。

    if (shape == BorderShape.SQUARE) {
        Position2D min = api.getMin(world);
        Position2D max = api.getMax(world);
    }

✨高级用法

边界事件

WorldBorderAPI 提供了事件，允许你在玩家接触边界时执行自定义操作。主要事件是 PlayerBorderCheckEvent。

• 监听事件：你可以在你的插件中监听这个事件。

    @EventHandler
    public void onBorderCheck(PlayerBorderCheckEvent event) {
        Player player = event.getPlayer();
        World world = event.getWorld();
        BorderShape shape = event.getBorderShape();
        // 你的自定义逻辑，例如取消传送并发送消息
        event.setCancelled(true);
        player.sendMessage(ChatColor.RED + "禁止穿越边界！");
    }

• 事件参数：该事件提供了玩家、世界、边界形状以及相关的坐标信息，方便你根据情况做出处理。

移除边界

使用 removeBorder 方法可以移除一个世界的边界。

api.removeBorder(world);

❓注意事项

• 使用 API 前，请确保服务器上已安装 WorldBorder 插件，否则 API 将无法加载。
• 始终检查获取的 WorldBorderAPI 实例是否为 null，以确保依赖的插件存在。
• 边界坐标是基于方块坐标的（X 和 Z 轴）。创建和检查时请使用 Position2D 对象。
• 合理使用边界事件，避免在事件处理中进行大量计算或阻塞操作，以免影响服务器性能。