AutoRail/README.md

AutoRail — 自动铺铁轨工业模组（Fabric 1.21.4，内置寻路）

按住 R+T 打开菜单，输入起始点、目标点和必经的途径点，模组用内置 A* 寻路 规划一条可铺轨的路线，然后控制玩家自动走到起点、边走边铺，直到目标点。 不依赖 Baritone，寻路与行走全部内置；间隔放置动力铁轨/探测铁轨/红石火把， 带材料不足预案、低血量紧急避险、自动进食，是完整的自动化铺轨流水线。

使用

1. 安装 Fabric Loader ≥0.16.9 与 Fabric API，把 autorail-<version>.jar 放进 mods/。
2. 进世界后按住 R+T 打开菜单（先按 T 弹出聊天栏也会被菜单替换掉，正常现象）。
3. 起始点留空 = 当前坐标；目标点必填；途径点可添加多个（按顺序经过）。 坐标格式支持：100 64 -200（x y z）、100 -200（x z，自动找地面）、~、~ 10 ~、~-5 等相对写法。
4. 点“开始铺轨”：先规划铁轨路线；若起点较远，模组会自动步行走到起点再开始铺设 （全程菜单/聊天栏显示进度，不卡游戏）。
5. 快捷栏需要铁轨；启用电气化后还需要动力铁轨（和按规则插的红石火把/探测铁轨）； 遇到悬空/水面会自动用圆石垫脚，没有则按预案处理。
6. 铺完可点 “沿线巡检”：沿路走回逐格检查断轨/顶部受堵/支撑流失，问题坐标逐条播报。
7. 铺轨过程中不要打开聊天/背包等界面（行走会暂停）；再按 R+T 可查看进度或点“停止”。

放置规则（电气化）

在菜单里点 “设置…” 配置，保存到 config/autorail.json：

设置项	默认	说明
动力铁轨间隔	16 格	每 N 格放 1 根动力铁轨（0 = 不放置）
探测铁轨间隔	0（关）	每 N 格放 1 个探测铁轨，矿车压过自动激活相邻动力轨
红石火把间隔	12 根动力轨	每 N 根动力铁轨旁的支撑方块侧面插 1 支火把持续供电
材料不足预案	等待补充	等待：原地暂停等快捷栏补料（超时可配）；跳过：缺火把/特殊轨就先铺普通轨保通
等待超时	60 秒	等待材料超过该时长自动停止并提示
低血量避险阈值	6	生命值低于阈值立即停下后退脱险（0 = 关闭）
自动进食阈值	16	饥饿度低于阈值自动吃快捷栏里的食物（0 = 关闭）

动力铁轨默认由旁边的红石火把持续供电；探测铁轨方案则适合“矿车压过才加速”的线路。

自动安全系统（铺轨期间后台运行）

• 低血量紧急避险：生命值 ≤ 阈值 → 松开前进、后退 + 跳跃拉开距离，恢复后自动回到岗位。
• 自动进食：饥饿 ≤ 阈值且血量未满 → 切换到快捷栏食物并长按使用键进食，吃完自动恢复铺轨。
• 材料不足预案：铁轨/圆石/火把缺货时按“等待/跳过”预案执行，不会卡死也不会铺出断头路。
• 卡住自救：行走受阻先跳跃脱困，持续卡住才报错停止；放置失败自动重试。

全程不弃单（换道续铺 + 自动搭桥）

• 换道续铺：步行到起点途中被卡住/缺圆石/路线不通时，不报错放弃—— 自动放弃步行路线，从玩家当前位置重新规划线路，直接铺到目标。
• 自动搭桥：步行寻路允许“悬空格”（水面之上、悬崖边缘），先垫圆石成型再踩上去； 搭桥代价高于绕路，能绕就绕、绕不过才搭。岩浆上不搭桥。

沿线巡检

铺轨完成后点 “沿线巡检”，玩家沿已铺线路走回一圈，逐格检查：

问题	含义
断轨	该格没有铁轨（被破坏/未铺上）
上方被堵	头顶两格被实体方块占用，矿车/玩家过不去
支撑流失	铁轨下方支撑消失（悬空/泡水），可能脱落
无法到达	巡检者被地形卡住，跳过该格继续检查后续线路

结果在聊天栏汇总播报（问题坐标 + 类型，最多显示 8 条），状态栏实时显示进度与问题数。

内置寻路（A*）

• 铁轨寻路：4 向移动、±1 格坡度、禁止掉头、“转弯+坡度”同格禁止（原版没有斜弯轨）； 每节点校验头顶两格可通行、下方支撑可垫补，避开水面/岩浆；转弯加价、复用既有铁轨打折。
• 步行寻路（去远处起点）：4 向 + 跳 1 格 + 落 3 格 + 可涉水 + 悬空格可搭桥（垫圆石）。
• 分片执行（每 tick 限额展开），不卡客户端线程。

铺设（合法交互）

• 切换快捷栏 + processRightClickBlock 右键放置，全程合法交互，绝不 world.setBlockState，多人服务器可信任。
• 放置节奏 200ms 一次；放置前自动看向目标方块；上坡自动跳跃；卡住自动检测。

代码结构

com.autorail
├─ AutoRailClient              # 入口：R+T 组合键 + 每 tick 驱动服务
├─ gui/AutoRailScreen          # 主菜单：起点/终点/途径点 + 巡检/设置入口
├─ gui/AutoRailSettingsScreen  # 设置：放置规则 / 预案 / 安全阈值
├─ config/AutoRailConfig       # Gson 持久化配置（config/autorail.json）
├─ service/AutoRailService     # 状态机：PLANNING → WALKING → LAYING → PATROLLING → DONE/FAILED
├─ service/RailExecutor        # 执行器：行走控制 + 合法放置铁轨/圆石/火把
├─ service/WalkExecutor        # 步行执行器：走到远处起点（含垫圆石搭桥）
├─ service/PatrolExecutor      # 巡检执行器：沿线逐格检查断轨/堵顶/支撑流失
├─ service/AutonomyController  # 自主行为：自动进食 / 低血量避险
├─ service/RailPlan            # 把间隔规则展开成逐节点放置计划
└─ pathing/                    # 内置寻路：RailPathfinder、WalkPathfinder、RailStep、WalkCell、CoordParser

开发

gradlew build          # 产物在 build/libs/autorail-<version>.jar

已知限制

• 复用既有铁轨不校验类型：老线路上的普通铁轨不会自动升级为动力铁轨（巡检会标出问题格）。
• 巡检只报告不修复：发现断轨后可对同线路再跑一次铺轨，复用折扣会让模组优先补齐缺口。
• 不破坏、不放置除铁轨/圆石/红石火把外的方块：遇到障碍会绕路而不是挖穿。
• 遇水会垫圆石架桥，岩浆列视为不可通行；步行搭桥同理（岩浆上不搭桥）。
• 红石火把在支撑方块侧面放置；若点位被后续地形占用，该处动力轨无供电（线路仍连通）。
• 自动进食吃的是快捷栏里的食物；食物全靠自带，模组不会杀生取食。
• 换道续铺要求目标点仍在寻路范围内（检查点包围盒外扩 48 格）；超远距离请加途径点分段。
• 基于客户端世界状态判定；服务器延迟时个别放置会失败，会自动重试。