Skip to content

api.md

Latest commit

 

History

History
218 lines (163 loc) · 7.53 KB

api.md

File metadata and controls

218 lines (163 loc) · 7.53 KB
Raw

metro-altroutes 开发者 API

metro-altroutes 目前不提供对外公开的 Java API。第三方插件可以通过以下方式集成：

PlaceholderAPI 占位符

如果服务器安装了 PlaceholderAPI，请使用 metroaltroutes 扩展标识符。

详情见 README PlaceholderAPI 节。

MetroAPI 集成

metro-altroutes 完全基于 Metro 的公开 API (org.cubexmc.metro.api.MetroAPI) 构建。所有 metro-altroutes 管理的线路操作最终通过 MetroAPI 执行：

  • 状态写入统一调用 MetroAPI#setLineStatus，以便触发 Metro 的 LineStatusChangeEvent（缓存失效与统计依赖它）；
  • 线路/站点几何查询使用 getStopManager().getBestStopContainingLocation(...)、getLinesForStop(...)；
  • 编译期使用 Metro 1.1.9（jar 由仓库自带：libs/metro-1.1.9.jar），构建时自动安装到本地仓库， 因为上游仓库已迁到 Gradle 且不能独立构建。

构建侧注意：paper-api 26.x 是 Java 25 字节码，需用 JDK 25 编译；本插件产出 Java 17 字节码， 因此同一个 jar 在 1.20.4 与 26.3 服务端均可加载。

内部 API（不保证稳定）

以下类对外暴露，但不保证跨版本兼容。如果其他插件需要集成，建议通过 MetroAPI + PlaceholderAPI 间接交互。

MetroAltroutes 入口

// 获取插件实例
MetroAltroutes plugin = MetroAltroutes.getInstance();

// 获取 MetroAPI
MetroAPI api = plugin.getMetroAPI();

// 获取缓存
RouteCache cache = plugin.getRouteCache();

// 获取数据管理器
LineDataManager dataManager = plugin.getLineDataManager();

// 获取铁路线路记录管理器
RecordManager recordManager = plugin.getRecordManager();

// 获取手动驾驶监听器
MinecartDriveListener drive = plugin.getMinecartDriveListener();

RouteCache 公开方法

LineStatus getStatus(String lineId);
String getSuspensionMessage(String lineId);
boolean isSuspended(String lineId);
boolean isMaintenance(String lineId);
boolean isBoardable(String lineId);
MetroAPI.LineSnapshot getSnapshot(String lineId);
List<LineSummary> getAllLineSummaries();
void invalidate(String lineId);
void invalidateAll();
void refreshAll();

替代路线查询请统一用 LineDataManager#getAlternativeRoutes（带优先级排序）。 RouteCache 早期版本里的替代路线索引已删除，避免与 Metro 的 alternativeRouteIds 形成两套数据源。

事件监听（稳定）

// Metro 侧的状态变更（含 Metro 自带的 /m line setstatus）
@EventHandler
public void onLineStatusChange(LineStatusChangeEvent event) { ... }

LineStatusListener 会据此使 RouteCache 立即失效，并从 NORMAL/MAINTENANCE → SUSPENDED 时累加暂停统计。

配置项（稳定）

路径 默认 说明
boarding.block-maintenance true 检修线路是否禁止非管理员乘坐
boarding.bypass-permission metroaltroutes.bypass 绕过权限节点
boarding.message-cooldown-ms 3000 拦截提示冷却
boarding.record-stats true 是否记录拦截统计
maintenance-assist.* 见 config.yml 速度显示 / 脱轨救援 / 手动推进
record.* 见 config.yml 铁路线路记录（开关 / 路径点上限 / 每人条数 / 记录时自动驾驶）
driving.* 见 config.yml W/S 手动驾驶（速度 / 加速度 / 刹车 / 是否影响运营车 / BossBar）

LineDataManager 公开方法

List<String> getAlternativeRoutes(String lineId);       // 优先级排序
void setAlternativeRoute(String lineId, String altId, int priority);
boolean removeAlternativeRoute(String lineId, String altId);
boolean clearAlternativeRoutes(String lineId);
void setAutoRecover(String lineId, int minutes);
boolean cancelAutoRecover(String lineId);
Integer getAutoRecoverMinutesLeft(String lineId);
void setSchedule(String lineId, String start, String end);
boolean clearSchedule(String lineId);
ScheduleEntry getSchedule(String lineId);
LineStats getStats(String lineId);
void recordSuspend(String lineId);
void recordIntercept(String lineId);
void recordAltRecommend(String lineId);
void reload();

LineStats 记录

int suspendCount();          // 暂停次数
int interceptCount();        // 拦截人数
int altRecommendCount();     // 推荐替代路线次数

ScheduleEntry 记录

boolean isWithinWindow(int currentMinute);
String getFormattedStart();  // HH:mm
String getFormattedEnd();    // HH:mm

RecordManager 公开方法

StartResult start(Player player, String name); // 开始记录（名称 1-24 字符）
RecordedLine stop(Player player);              // 结束并保存；未采集到有效轨道返回 null
boolean cancel(Player player);                 // 取消记录
boolean isRecording(Player player);
SessionSnapshot getSession(Player player);     // 实时进度（方块数/长度/用时）
List<RecordedLine> getAll();                   // 按创建时间排序
List<String> getNames();
RecordedLine get(String name);
boolean delete(String name);
void save();

记录数据保存在 plugins/metro-altroutes/recordings.yml；RecordedLine#points() 返回压缩后的折线顶点（int[]{x, y, z}）。

MinecartDriveListener 公开方法

boolean isDriving(Player player);
boolean setDriving(Player player, boolean enabled, boolean notify);
boolean enableForRecording(Player player);     // 记录开始时自动开启（原本未开启时）
boolean disableIfAutoRecording(Player player); // 记录结束时关闭“自动开启”的驾驶
boolean isInputApiAvailable();                 // 服务端是否支持玩家输入事件
static boolean supportsPlayerInput();          // 静态探测（Paper 1.21.4+）

MinecartDriveListener 依赖 Paper 1.21.4+ 的 PlayerInputEvent；旧版服务端上 该监听器仍可加载，但 isInputApiAvailable() 为 false 时手动驾驶整体停用。 驾驶参数通过 MetroAltroutes 的 driving.* 配置 getter 读取。

集成示例

检查线路是否可乘坐

MetroAltroutes plugin = MetroAltroutes.getInstance();
RouteCache cache = plugin.getRouteCache();

if (!cache.isBoardable("line1")) {
    // 线路暂停或维护
}

获取线路统计数据

LineDataManager dm = MetroAltroutes.getInstance().getLineDataManager();
LineDataManager.LineStats stats = dm.getStats("line1");

int suspended = stats.suspendCount();
int intercepted = stats.interceptCount();

获取替代路线（按优先级排序）

List<String> alts = dm.getAlternativeRoutes("line1");
// 返回 ["line2", "line3"] 按优先级升序

读取铁路线路记录

RecordManager rm = MetroAltroutes.getInstance().getRecordManager();
RecordManager.RecordedLine line = rm.get("环城线");
if (line != null) {
    int blocks = line.blocks();          // 轨道长度（格）
    List<int[]> vertices = line.points(); // 压缩后的折线顶点
}

稳定性说明

API 级别 稳定性 说明
PlaceholderAPI 占位符 ✅ 稳定 语义化版本内保证兼容
MetroAltroutes.getInstance() ⚠️ 实验性 可能随插件重构改变
LineDataManager 方法 ⚠️ 实验性 方法签名可能调整
RecordManager 方法与记录数据 ⚠️ 实验性 记录存储格式可能调整
MinecartDriveListener 方法 ⚠️ 实验性 驾驶行为与参数可能调整
RouteCache 方法 ⚠️ 实验性 缓存策略可能调整