ArdaRegions - 阿尔达区域

ArdaRegions

适用于Minecraft服务器的区域探索与追踪模组。在地图上定义区域，让玩家通过探索来发现它们。

功能说明

区域定义

在游戏中定义多边形区域。您可以为其命名、添加描述、设置为可发现状态，并建立父子级联关系。

探索发现

当玩家首次进入某个区域时，该区域将被标记为已发现，玩家会收到“已发现”弹窗提示。玩家还可在屏幕左上角查看当前位置信息。

地图类型

支持使用服务器内置的BlueMap，或上传区域覆盖层来绘制区域。

运行要求

• Minecraft 1.20.1
• Fabric Loader
• Fabric API
• Fabric Permissions
• BlueMap

可选组件

• LuckPerms

安装配置

1. 服务器端安装

• 将ArdaRegions的jar文件放入服务器/mods/目录
• 启动服务器 - 数据库和配置文件将自动生成

2. 客户端安装

• 将ArdaRegions添加到客户端/mods/目录
• 启动客户端

3. 地图瓦片设置

• 安装并运行BlueMap，使其渲染您的世界
• 在服务器上执行命令/ardaregions processtiles，将BlueMap的瓦片转换为ArdaRegions格式
• （可选）在客户端config/arda-regions/map-overlay.json中添加额外地图覆盖层。将worldSize设置为图像对应的Minecraft方块宽度，worldX和worldY设置为Minecraft世界左上角坐标
• 通过/ardaregions panel中的地图覆盖层按钮切换不同地图

4. 权限设置

ArdaRegions支持使用内置的Minecraft OP权限系统，或通过Fabric Permissions API实现的权限系统（如LuckPerms）。

若使用LuckPerms或其他实现Fabric Permissions API的模组，请为用户授予ardaregions.admin权限节点以允许使用管理员命令。

命令列表

• /ardaregions panel – 打开区域地图（管理员）
• /ardaregions processtiles – 处理BlueMap瓦片（管理员）
• /ardaregions resetprogress – 重置自己的探索进度
• /ardaregions resetprogress – 重置其他玩家的探索进度（管理员）
• /ardaregions view - 查看指定区域的3D显示（管理员）
• /ardaregions viewall - 查看所有区域的3D显示（管理员）
• /ardaregions viewnone - 关闭3D显示（管理员）
• /ardaregions viewcurrent - 查看当前区域的3D显示（管理员）

鸣谢

衷心感谢所有参与本模组开发的贡献者：

• Xone：参与测试、错误排查，并制作纹理与图形资源
• Fornad：参与测试、错误排查，成为首位用户
• 整个ArdaCraft团队对本项目开发的支持
• Blue（BlueMap作者）：协助使用其模组的瓦片系统

API接口

ArdaRegions提供客户端API，允许其他模组利用区域事件（如发现事件、当前区域、区域列表等）。

获取API

入口点方式（推荐）：

在fabric.mod.json中配置：

"entrypoints": {
  "arda-regions:api": [
    "your.mod.YourApiEntrypoint"
  ]
}

您的类需实现ArdaRegionsApiEntrypoint接口：

import mc.ardacraft.ardaregions.api.ArdaRegionsAPI;
import mc.ardacraft.ardaregions.api.ArdaRegionsApiEntrypoint;

public class YourApiEntrypoint implements ArdaRegionsApiEntrypoint {
    @Override
    public void onApiReady(ArdaRegionsAPI api) {
        // 存储api实例，使用getRegionAPI() / getExplorationAPI() / 事件系统
    }
}

延迟获取方式：

通过ArdaRegionsAPI.getInstance()获取API实例（若模组未加载将抛出异常）。建议使用入口点方式以确保API就绪时立即获取。

区域API (IRegionAPI)

通过api.getRegionAPI()获取。

探索API (IPlayerExplorationAPI)

通过api.getExplorationAPI()获取。

数据类型

ApiRegion

包含id、name、parentId、childrenIds、polygons、metadata属性。

getDescription()方法可获取metadata中的描述信息（如果存在）。

ApiPolygon

包含vertices（ApiPoint2D列表）、minY、maxY、world属性。

isWithinYBounds(int y)方法用于Y坐标检查。

ApiPoint2D

包含x、z坐标（双精度浮点数）。通过getX()、getZ()方法访问。

所有类型均位于mc.ardacraft.ardaregions.api.data包中，均为不可变对象。

事件系统

所有事件均为Fabric Event类型。通过event.register(callback)注册监听器。

使用示例：

api.getRegionDiscoveredEvent().register((playerId, regionId) -> {
    // ...
});