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

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

## 使用

1. 安装 [Fabric Loader ≥0.16.9](https://fabricmc.net/use/) 与 [Fabric API](https://modrinth.com/mod/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 一次；放置前自动看向目标方块；上坡自动跳跃；卡住自动检测。

## 代码结构

```text
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
```

## 开发

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

## 已知限制

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