metro-altroutes — Metro 附属插件

metro-altroutes 是一款面向高端 Minecraft 服务器的 Metro 扩展插件，专注于轨道交通运营管理、乘车行为控制和备用线路调度。 它基于 Metro API 进行深度集成，提供稳定、可扩展且符合大型服务器运维需求的运营逻辑； 并在**检修（maintenance）**状态下提供速度显示、脱轨救援与手动控车能力。

📖 指令 · 架构 · api · 变更日志

---

产品定位

metro-altroutes 的设计目标是为 Metro 生态提供一套可预测的线路运营控制方案，适用于商业服务器、城市交通网络和高并发玩家环境。通过对线路状态、乘车权限和暂停公告的集中控制，插件将复杂的轨道运营调度转化为易于管理的指令集。

---

关键能力

能力	说明
运营状态策略	支持正常、暂停、检修三种线路状态；写入统一走 Metro 的 MetroAPI#setLineStatus，会触发 LineStatusChangeEvent
乘车拦截	检修线路阻止非管理员上车（metroaltroutes.bypass 可绕过）；暂停线路由 Metro 本体拦截，本插件不再重复
统一公告系统	允许为暂停/检修线路配置提示文本，拦截时同步推送
智能替代路线	为暂停线路推荐可用替代线路，支持优先级排序，并与 Metro 的 alternativeRouteIds 双向同步
自动恢复调度	设置倒计时自动恢复正常运营，无需人工干预
计划维护时段	按设定时间自动暂停/恢复，适用于定期维护场景
运行统计	记录暂停次数、拦截人数和推荐替代路线次数
检修乘车协助	检修线路上显示速度 BossBar（m/s）、脱轨自动换车并记录坐标、失速时手动控制速度
铁路线路记录	乘坐矿车沿铁路行驶即可录制线路：逐 tick 采样轨道方块、自动去重并压缩为折线，保存到 recordings.yml，支持列表/详情/删除
W/S 手动驾驶	/maroutes line drive 开关：W 加速、S 刹车/倒车、松开按键滑行，BossBar 实时显示速度；基于 Paper 1.21.4+ 的玩家输入事件，旧版服务端自动降级停用
缓存一致性	监听 Metro 的 LineStatusChangeEvent，任何来源的状态变更都会立即失效缓存
运行时兼容	原生兼容 Paper 与 Folia，所有实体/世界操作均走对应调度器

---

适用场景

• 公共交通服务器：实现地铁与轻轨线路的精细化运营管理
• 城市模拟服务器：控制停运通知、备用路线和线路维护状态
• 运营型服务器：在高并发环境下保证暂停线路行为的稳定性
• Metro 生态集成：为 Metro 提供线路调度与用户提示扩展

---

依赖信息

• 服务端：Paper / Leaf 1.20.4 ~ 26.3（编译目标为 paper-api 26.3，产物是 Java 17 字节码，同一份 jar 通吃）
• Folia 运行时（plugin.yml 已声明 folia-supported: true）
• Metro 1.1.9（插件编译所用版本；Metro 自身需能运行在目标服务端上）
• PlaceholderAPI（可选，用于占位符支持）

Metro 依赖源仓库：

https://github.com/CubeX-MC/Metro

插件使用的 Metro Maven 坐标：

org.cubexmc:metro:1.1.9（由仓库自带的 libs/metro-1.1.9.jar 提供）

注意：Metro 没有发布到 Maven Central，且上游仓库已迁到 Gradle、又缺少 settings.gradle.kts / gradlew / modules （依赖自研 cubex-* 插件），无法独立构建。因此本项目直接携带官方提供的 jar： libs/metro-<version>.jar，pom 用 system scope + systemPath 直接引用它（不参与传递依赖，也不会被打进产物）。 升级方式：把新的 metro-x.y.z.jar 放进 libs/，并把 pom.xml 里的 metro.version 改成同一版本。

---

构建

需要 JDK 25 与 Maven：paper-api 26.x 是 Java 25 字节码（major 69），用 JDK 17/21 编译会直接报 class file has wrong version 69.0。产出的字节码仍然是 Java 17（maven.compiler.release=17）， 所以同一个 jar 在 1.20.4 与 26.3 服务端都能加载。

# JAVA_HOME 指向 JDK 25
mvn package

# 临时用其他 Metro jar 验证（例如 angushushu 给的新版）
mvn -Dmetro.jar=/path/to/metro.jar package

# 产物
target/metro-altroutes.jar

Metro 依赖不需要联网、也不需要额外步骤：libs/metro-1.1.9.jar 随仓库携带，pom 直接指向它。 （不能用 provided + 仓库坐标：Maven 在跑生命周期前就解析依赖，构建期再 install 是来不及的。）

编译时已关闭注解处理（<proc>none</proc>）：Metro 的 shaded jar 残留了指向已重定位类的 javax.annotation.processing.Processor 声明，会让 javac 直接报“服务配置文件不正确”。

---

安装说明

1. 确保服务器已安装 Metro 插件。
2. 将 metro-altroutes.jar 放入 plugins/ 目录。
3. 重启服务器或执行插件热加载。
4. 使用 /maroutes（或 /metroalt）命令集进行线路管理与调度。

为什么不叫 /m：/m（以及 /metro、/l）已由 Metro 本体注册（/m line setstatus、/m gui 等）。 两个插件抢同一个别名会按加载顺序互相顶掉，因此本插件的命令固定使用 /maroutes 与 /metroalt， 与 Metro 自带的 /m ... 井水不犯河水。

配置文件

插件首次启动会生成 plugins/metro-altroutes/config.yml：

配置项	默认值	说明
boarding.block-maintenance	true	线路检修时是否禁止非管理员乘坐
boarding.bypass-permission	metroaltroutes.bypass	绕过检修禁乘所需的权限
boarding.message-cooldown-ms	3000	拦截提示冷却，避免刷屏
boarding.record-stats	true	是否记录拦截统计
maintenance-assist.enabled	true	检修乘车协助总开关
maintenance-assist.speed-display.*	—	BossBar 速度显示（刷新间隔、满进度速度）
maintenance-assist.derail-rescue.*	—	脱轨救援（判定 tick、冷却、单次上限）
maintenance-assist.manual-throttle.*	—	失速手动推进（阈值、推进速度、坐标记录）
record.*	—	铁路线路记录（开关、单条路径点上限、每人记录数、记录时是否自动开启手动驾驶）
driving.*	—	W/S 手动驾驶（速度/加速度/刹车参数、是否影响 Metro 运营车、速度 BossBar）
line-data.*	{}	替代路线优先级 / 自动恢复 / 维护时段 / 统计，由命令自动维护

---

命令与操作

所有子命令都挂在 line 下，通过 /maroutes 或 /metroalt 调用。

指令	描述
line setstatus <线路ID> <状态>	设置线路当前运营状态（与 Metro 自带的 /m line setstatus 语义一致）
line setsuspensionmsg <线路ID> <消息>	设置暂停/检修线路的提示文本
line setaltroute <线路ID> <替代ID> [优先级]	为当前线路指定备用路线（可选优先级）
line clearaltroute <线路ID> [替代ID]	清除备用路线（可指定 ID 单条删除，两边数据源同步）
line setautoresume <线路ID> <分钟>	设置自动恢复倒计时，到期自动恢复正常
line cancelautoresume <线路ID>	取消自动恢复设置
line setschedule <线路ID> <开始>-<结束>	设置计划维护时段（HH:mm-HH:mm）
line clearschedule <线路ID>	取消计划维护时段
line stats <线路ID>	查看线路运行统计数据
line status <线路ID>	查询线路当前状态
line info <线路ID>	查看线路详细运营信息
line list	列出所有线路状态与配置
line record start <名称>	开始记录铁路线路（需乘坐矿车沿轨道行驶）
line record stop	结束并保存当前记录（自动压缩路径）
line record cancel	取消当前记录（不保存）
line record status	查看当前记录的实时进度
line record list	列出已保存的线路记录
line record info <名称>	查看记录详情（长度、路径点、起点/终点）
line record delete <名称>	删除记录（记录创建者或管理员）
line drive [on|off]	开关 W/S 矿车手动驾驶（不带参数则切换）
reload	重新加载 config.yml、运行数据与线路缓存（需 metroaltroutes.admin）

管理类子命令的权限以 Metro 的所有权模型为准（控制台 / metro.admin / 线路拥有者 / 线路管理员）， 另外拥有 metroaltroutes.admin 的玩家可管理全部线路；查询类子命令需要 metroaltroutes.use。

状态说明

状态	含义	是否允许上车
normal	正常运营	是
suspended	暂停运营	否（由 Metro 本体拦截）
maintenance	检修中	否（由本插件拦截，需 metroaltroutes.bypass 才能绕过）

检修禁乘的拦截行为可用 boarding.block-maintenance 关闭。 线路拥有者与线路管理员始终不受限制。

---

检修乘车协助

线路处于 maintenance 时，玩家乘坐矿车会得到以下协助（全部受 maintenance-assist.* 控制， 暂停线路的拦截仍由 Metro 本体负责）：

行为	说明
速度显示	用 BossBar 显示当前速度（m/s）。不使用 actionbar / 计分板，避免与 Metro 的行程显示互相覆盖
脱轨救援	矿车连续脱离轨道超过 confirm-ticks 后，把坐标记到聊天框与控制台，并就地生成一辆普通矿车把玩家接上去
失速手动控制	矿车在轨道上但速度接近 0 时记录一次坐标，并让矿车持续朝玩家视线方向获得速度（Metro 只在既定方向上补推，无法改向）

注意：

• 救援生成的是普通矿车（不带 Metro 的运营标记），不再由 Metro 的列车任务驱动，改用“朝哪看就往哪走”的手动方式继续行驶。
• 单次乘坐救援有次数上限（derail-rescue.max-per-ride），避免反复脱轨刷车。
• 脱轨与失速的坐标会写到控制台（[检修协助] …），方便管理员事后修轨道。

---

铁路线路记录

把一条铁路“录”下来：坐矿车沿轨道行驶，插件逐 tick 记录经过的轨道方块。

命令	说明
/maroutes line record start <名称>	开始记录（需乘坐矿车；名称支持中文/字母/数字/下划线/连字符，1-24 字符）
/maroutes line record stop	结束并保存（自动把直线段压缩成折线，显示轨道长度与路径点数）
/maroutes line record cancel	取消本次记录（不保存）
/maroutes line record status	查看已采集的轨道方块数、长度与用时
/maroutes line record list	列出已保存的记录
/maroutes line record info <名称>	查看详情（世界、创建者、长度、路径点、起点/终点）
/maroutes line record delete <名称>	删除记录（仅创建者或 metroaltroutes.admin）

说明：

• 记录的数据保存在 plugins/metro-altroutes/recordings.yml。
• 只在矿车位于铁轨上时采样；连续重复的方块自动去重。
• 单条记录超过 record.max-points 会自动保存并结束；每位玩家默认最多保有 record.max-per-player 条记录。
• 若开启 record.auto-drive（默认），开始记录时会自动为记录者开启 W/S 手动驾驶，方便一边开车一边录制。

W/S 矿车手动驾驶

用 /maroutes line drive 开关。开启后乘坐矿车即可像司机一样控制速度：

操作	效果
按 W	沿当前行驶方向持续加速（静止时沿玩家视线方向起步），直到 driving.max-speed
按 S	速度较高时刹车减速；接近静止后向反方向倒车（上限 driving.max-reverse-speed）
松开按键	滑行减速（driving.coast-deceleration）

说明：

• 驾驶时 BossBar 实时显示速度（m/s）与当前油门状态，可用 driving.show-speed-bar 关闭。
• 只调整速度大小、不强制方向，铁轨的自动转向/爬坡不受影响。
• 默认不干预 Metro 的运营列车（driving.affect-metro-carts: false），避免与 Metro 的自动行车任务冲突；如需允许控制运营列车可改为 true。
• 该功能依赖服务端的玩家输入事件（Paper 1.21.4+ / 26.x）；旧版服务端会自动停用，/maroutes line drive 会给出提示。
• 与检修协助的关系：玩家开启手动驾驶时，检修线路上原有的“失速自动推进”会让位，不再和手动驾驶抢速度。

---

权限说明

权限	作用	默认值
metroaltroutes.admin	管理线路运营与公告（含线路拥有者之外的全局管理）	OP
metroaltroutes.use	查看线路状态与信息	所有人
metroaltroutes.bypass	线路检修期间仍可乘坐	OP
metroaltroutes.record	记录/查看/管理自己的铁路线路记录	所有人
metroaltroutes.drive	使用 W/S 手动驾驶矿车	所有人

---

PlaceholderAPI 占位符

如果服务器安装了 PlaceholderAPI，可以使用以下占位符（将 <line> 替换为实际线路 ID）：

占位符	返回值
%metroaltroutes_line_status_<line>%	线路状态：normal / suspended / maintenance
%metroaltroutes_line_status_display_<line>%	带颜色图标的运营状态文本
%metroaltroutes_line_boardable_<line>%	是否可乘坐：true / false
%metroaltroutes_line_suspended_<line>%	是否暂停：yes / no
%metroaltroutes_line_suspension_msg_<line>%	暂停公告文本
%metroaltroutes_line_altroutes_<line>%	替代路线列表（逗号分隔）
%metroaltroutes_line_altroute_count_<line>%	替代路线数量
%metroaltroutes_line_name_<line>%	线路名称
%metroaltroutes_line_terminus_<line>%	线路终点站
%metroaltroutes_line_stop_count_<line>%	站点数量
%metroaltroutes_line_owner_<line>%	线路拥有者
%metroaltroutes_line_color_<line>%	线路颜色代码
%metroaltroutes_line_stats_suspend_<line>%	暂停次数统计
%metroaltroutes_line_stats_intercept_<line>%	拦截人数统计
%metroaltroutes_line_stats_alt_recommend_<line>%	推荐替代路线次数
%metroaltroutes_line_autoresume_<line>%	自动恢复剩余分钟数（0=未设置）
%metroaltroutes_line_schedule_<line>%	计划维护时段（如 02:00-04:00）

示例计分板配置：

# 在计分板或插件中显示线路状态
%metroaltroutes_line_status_display_line1%
%metroaltroutes_line_altroutes_line1%

线路 ID 自身包含下划线（如 line_1）也支持，占位符名会自动按最长前缀匹配。 line_stats_*、line_autoresume、line_schedule 取自本插件的运行数据，线路不在缓存中时也能返回。

---

使用示例

# 将 1 号线路设置为暂停
/maroutes line setstatus line1 suspended

# 为暂停线路设置通知文本
/maroutes line setsuspensionmsg line1 "&c线路临时暂停，预计 2 小时后恢复。"

# 设置备用线路（指定优先级）
/maroutes line setaltroute line1 line2 50

# 查询线路状态
/maroutes line status line1

# 列出所有线路状态
/maroutes line list

# 查询线路统计数据
/maroutes line stats line1

# 设置自动恢复（30 分钟后自动恢复正常）
/maroutes line setautoresume line1 30

# 设置计划维护时段（每天 02:00-04:00 自动暂停）
/maroutes line setschedule line1 02:00-04:00

# 取消计划维护时段
/maroutes line clearschedule line1

# 将线路恢复为正常运营
/maroutes line setstatus line1 normal

# 移除某条备用线路
/maroutes line clearaltroute line1 line2

# 将线路设为检修（非管理员将无法乘坐）
/maroutes line setstatus line1 maintenance

# 开始记录铁路线路（坐上矿车沿铁路行驶即可）
/maroutes line record start 环城线

# 结束并保存记录
/maroutes line record stop

# 查看已保存的线路记录
/maroutes line record list

# 开关 W/S 手动驾驶（W 加速 / S 刹车、倒车）
/maroutes line drive on

---

项目架构

src/main/resources/
├── plugin.yml                # 命令、权限与版本号
└── config.yml                # 乘车限制 / 检修协助 / 运行数据（必须随包发布）

src/main/java/top/chenray/metroaltroutes/
├── MetroAltroutes.java       # 插件入口：容错启用、Folia 调度封装、PAPI 注册、配置读取
├── cache/
│   └── RouteCache.java       # 线路状态缓存（TTL 30 秒按需刷新，状态变更即时失效）
├── commands/
│   └── LineCommand.java      # 命令解析与业务逻辑入口
├── data/
│   ├── LineDataManager.java  # 数据层：替代路线优先级、自动恢复、计划调度、运行统计
│   └── RecordManager.java    # 铁路线路记录：逐 tick 采样轨道、压缩折线、持久化到 recordings.yml
├── hooks/
│   └── PlaceholderHook.java  # PlaceholderAPI 扩展，暴露线路数据为占位符
└── listeners/
    ├── BoardingListener.java          # 检修线路乘车拦截与替代路线建议
    ├── LineStatusListener.java        # 监听 Metro 状态变更，同步缓存与统计
    ├── MaintenanceAssistListener.java # 检修乘车协助：速度 BossBar / 脱轨救援 / 手动推进
    ├── MinecartDriveListener.java     # W/S 手动驾驶：按键状态 -> 矿车速度
    └── InputTrackingListener.java     # 玩家输入事件桥接（仅 Paper 1.21.4+ 注册）

---

版本与维护

当前版本 1.4.0：新增铁路线路记录（/maroutes line record）与 W/S 矿车手动驾驶（/maroutes line drive）； 编译目标为 Paper 26.3（仍兼容 1.20.4 起的旧服务端），要求 Metro 1.1.9（编译所用版本，jar 随仓库携带），构建需 JDK 25。 本项目面向 Metro 生态持续迭代，后续版本将进一步增强线路管理策略、公告配置和兼容性支持。 如果希望定制化功能，请在仓库提交 issues 或 PR。