配置与数据文件
问道的东西分成两堆：配置是「我习惯怎么走」——默认交通方式、偏好、容差、要不要读机械动力和 MTR，
以及日志与浏览器地图怎么开；数据是「我在这个世界修了什么」——路网、地点、线路。配置在
config/howtogo-client.toml，数据在 config/howtogo/，
两堆都在你自己的客户端上，都按存档或按客户端分开，互相之间不会写坏。
配置放在哪、怎么改
客户端配置由 NeoForge 生成，文件是 config/howtogo-client.toml。
绝大多数人不需要打开这个文件：进 模组列表 → HowToGo | 问道 → 配置
就是同一个文件的配置界面。0.2.2 起这个按钮真的能打开界面——它读的是生成
howtogo-client.toml 的同一份声明，所以界面上列出的项、默认值、
可填范围与注释，和文件里的完全一致，不会出现「界面上改了、文件里却没变」。
每一项都有中英文标题，改完保存即时生效；road_colors /
transit_line_colors 这两节在界面上改最方便。
这些值是在用到的时候才读的，所以改完保存即可，不必为此重启客户端； 实在拿不准的时候重启一次总是安全的。配置是客户端本地的：你和朋友在同一台服务器上玩， 各自改各自的，谁也不会影响谁。
交通方式、路线偏好和语音开关还有第二个入口：「选择目的地」界面里可以直接点。 那两个入口写的是不同的地方，见下面的运行时偏好。
导航：方式、偏好与绕行
| 键 | 默认值 | 说明 |
|---|---|---|
default_travel_mode |
"walk" |
导航从哪种交通方式开始，也是预估时间的计算依据。可写
"walk"（步行）、"drive"（驾车）、"transit"（公共交通）。
它只是「开局默认」，你在界面里点过别的以后就以你点的为准。
|
route_preference |
"fastest_time" |
「最好的一条路」是什么意思。"fastest_time" 按每种等级的实际速度给路段加权；
"shortest_distance" 不看速度，只找最长直线意义上的最短路线。
同一条河的桥、同一条冰道，两种口径会给出不同的答案。
|
avoid_road_classes |
[] |
完全不走哪些等级。可写
highway、road、path、rail、
water、ice；写错的条目会被单独忽略，
而不是让整份配置失效——一个过期的名字只让你少避让一条等级，不会让你突然没有路线。
|
prefer_major_roads |
false |
开启后各等级不是被禁掉，而是按权重变贵：高速 ×1.0、公路 ×1.25、小路 ×1.8。 权重只乘在搜索代价上、绝不碰速度，所以「最快时间」与「最短距离」两种口径都会生效 （0.2.1 之前它只压在「小路」上，而车根本不许上小路——这个开关在开车时勾了等于没勾； 「最短距离」口径下更是完全没用）。×1.25 的意思是「为了走高速，绕 25% 以内都值得」。 直接禁掉某一级会让一些行程无解，而玩家在地图上看不出原因，所以这里选了「劝退」而不是「禁止」。 |
fall_back_to_walking_when_slower |
true |
所选方式比直接走过去还慢、或者在该路网里根本没有解时，改按步行规划， 并在读数里说明「为什么不是你要的方式」。真实存在的公交行程不会 被这样替换——那时步行是作为另一种选择提出来的，不是顶替。关掉它，慢就慢，如实显示。 |
walk_offroad_blocks |
32（0~4096） |
步行时最多允许离开道路走多远，单位是格，0.2.2 新增。
超过这个距离的目的地或路尽头，直接判「没有路线」，不再画一条横穿地图的直线——
以前这条路径没有上限，于是山那边的目的地也能得到一条「走过去」的假路线。
数值越小越严格。驾车不再越野：它只允许「车还在路面上」的那点距离（最宽路面的半宽），
停在路边可以、停在田里不行；公共交通的乘车段也只保留站台到轨道的接驳
（station_snap_blocks，默认 32 格），超过就没有这段车程。
近距端点的合并对步行只在地表层 0 生效：高架与地下的两截路要接，
请自己补一个节点；车仍按同层规则。
|
路网修复与偏离判定
| 键 | 默认值 | 说明 |
|---|---|---|
repair_road_joins |
true |
把「看着连上、其实没连上」的路在规划之前修好。 两条路穿过同一个节点是一条路；交叉而过、或差一格停住的两条路是两条，路由器不会从一条走到另一条。 开启后：落在路段中间的节点会把路段拆开，交叉的两条路互相打断， 然后把这些几乎重合的节点并成一个路口。只在「同一辆车两条路都走得通」且高度相近时才并， 所以桥还是桥，不会把上下两层接在一起。0.2.1 起这个高度判断的容差 随水平间距放大：两端水平差 3 格、垂直差 8 格是上坡的路，必须接； 水平差 2 格、垂直差 36 格是桥，必须不接——固定容差两边都会错。 关掉就完全按你画的样子走。 |
on_road_tolerance_blocks.* |
高速 24 / 公路 16 / 小路 8 铁路 16 / 水路 32 / 冰道 12 |
一个等级一项（highway / road / path /
rail / water / ice），
表示「离画出来的线多远还算在这条路上」，单位是格，可调范围 1~128。
它量的不是路的宽度，而是画笔那条线——而那条线是画在路中间的一条折线，
所以分隔式高速的对向车道、路边的行人、飘离运河中线的船，都在走自己那条路。
0.2.1 把默认值整体调大（原来是高速 11 / 公路 8 / 小路 5 / 铁路 6 / 水路 10 / 冰道 8）：
宽的路本来就该比羊肠小道更宽容，而水路最大是故意的——船本来就不拴在一条线上，运河比任何街道都宽；
小路最小也是故意的，小路本来就窄。
|
station_snap_blocks |
32.0（1~256） |
离行程停靠的某个站点多近算「就在站上」，单位是格；在这个半径内不判偏航。 它同时是报站的距离基准。站台、站前广场、天桥离轨道中线几十格是常事，过去一走出路线容差就被判偏航。 换乘站是几条线路的多个站点凑成的一个地点，每个站点周围各自生效， 所以从一个站台走到另一个站台换乘也不会被判成偏离。 |
容差只影响一件事：什么时候重新规划。只有当玩家离开「本该在的那条路」超过它的容差， 才会触发偏航重算；贴着路边走、或者走路时晃来晃去，都不该让你听见一遍又一遍的「已偏离路线」。
已经写过 howtogo-client.toml 的实例不会被新默认值改动。
NeoForge 只在文件不存在时写入默认值，所以从旧版本升上来的人，文件里仍是旧的一组容差。
要享受新的默认值：自己改那一节，或者把整个 [on_road_tolerance_blocks] 删掉让游戏重写。
配色
0.2.2 把颜色从代码里拿出来，分成两组，都写在 config/howtogo-client.toml 里，
也都能在模组列表的配置界面里改。两组支持同样的写法：#RRGGBB，
或者带透明度的 #AARRGGBB。写错的值被忽略（日志里说一次）并保留原来的颜色，
不会让整份配置失效；改完即时生效，不用重启。
road_colors：六个道路等级的颜色
一节六项，分别对应高速、公路、小路、铁路、水路、冰道，各填一个颜色。 改的是「路本身」的颜色，而且所有地方读同一份设置：世界地图、导航小地图、 「选择目的地」界面、图例、浏览器地图都读它——所以网页地图与游戏里不会出现两套配色。
transit_line_colors：四种线路类型的颜色
一节四项，对应铁路、水路、公路、冰道四种线路类型。
它改的是线路本身的线与这条线名下的每一个站点标记；
线路底下那条轨道仍按 road_colors 画，两者互不影响。
默认值就是模组一直使用的配色，不写这一节时和以前一模一样；
从 MTR 读进来的线路同样按类型取色，与手画线路用同一套规则。
公共交通与语音
| 键 | 默认值 | 说明 |
|---|---|---|
transit_wait_seconds |
60.0 |
等一次车的平均秒数，范围 0~3600。每次登乘都算一次：第一次上车算，
中途换乘再算。这里没有时刻表可读，所以它是平均等待而不是发车时间——两分钟一班的车就是 60。
它同时参与搜索和预计时间：省下 40 秒走路却多等两分钟车的方案，本来就没道理被推荐。
如果你修的是「车永远停在那儿」的线路，填 0 是正当答案。
|
transit_board_only |
true |
公共交通导航是否只报站、不报转向：在车上的那一段不再提示左转右转，
改说上车、到站、还有几站与在哪换乘；走到车站与下车之后的步行段照旧是普通转向提示。
0.2.1 起默认改成开——乘客在车上做不了转向，能做的决定只有「哪一站下车」
和换乘时「上哪条线」。「选择目的地」界面里有同一个开关。
已经写过 route_preferences.json 或 howtogo-client.toml
的实例不受影响：文件里的值优先，要回到新默认就在界面里打开它，
或在 route_preferences.json 里把 transitBoardOnly 改成
true、或删掉这一项（缺项按配置的默认算）。
|
voice_announcements |
false |
是否把导航事件念出来：前方转弯、现在转弯、到达、偏离路线。 默认关闭，因为语音会盖住客户端正在放的声音，而每个路口都念一句是个人口味。 这是唯一的语音开关——它故意不去管 Minecraft 自己的朗读者设置， 所以打开它就一定听得到。「选择目的地」界面里也有同一个开关，给从不打开这个文件的人用。 |
语音听起来别扭（例如英文数字被读成中文）不是这一项能解决的，原因与办法见 常见问题与限制。
机械动力铁路
| 键 | 默认值 | 说明 |
|---|---|---|
create_train_tracks |
true |
是否读取机械动力的铁轨并画在地图上、把它的车站当成目的地。 关掉等于把整个图层清空，下一秒生效；怎么关都不会动你已经画好的路。 |
create_track_block_ids |
["create:track"] |
哪些方块算「铁轨」，按方块注册名匹配，所以附属模组加的轨道方块可以直接填进来。
没装的模组的 id 填了也不会报错——世界里根本没有那种方块，也就匹配不到任何东西。
create:fake_track（Create 自己的「轨道标记」隐形方块）故意没有列进去：
它是标记而不是路面，列进去会在没有轨道的地方画出线来。 |
create_station_block_ids |
["create:track_station"] |
哪些方块的位置成为目的地，会单独列在目的地列表的一个来源里。 它们的名字是按坐标取的：Create 把站名放在服务端的铁路数据里，能到客户端的方块实体并不带名字， 所以这里没有名字可读。 |
create_track_scan_radius |
192 |
回退到扫描方块时，以玩家为中心读多大范围（格），范围 16~512。 是正方形而不是圆，因为区块是方的。一轮扫描的代价随它的平方增长，所以调大是让一轮更久， 而不是让某一瞬间更卡——单次做多少活由下面那一项封顶。 |
create_track_chunks_per_second |
20 |
这个功能全部的开销都在这里：每秒最多读几个区块，一秒一批，从最近的区块开始。 不含铁轨的区块每段只做一次调色板检测，只有调色板里真的有铁轨的区块才会逐格走一遍。 默认半径下每秒 20 个区块，大约半分钟扫完整个范围；脚底下的区块无论这一项写多少都每秒读一次。 想扫得更快就调大；某一批偶尔卡顿就调小。读出机械动力自己的轨道图时这一项不生效。 |
这一项改过名字：旧键名是 create_track_chunks_per_tick，那是「每 tick」的数字；
节奏改成「每秒」以后键名跟着改了，旧文件里那一行不再被读取。
如果你从旧版本升上来，把旧行删掉即可，新的默认值 20 会在那里。
阡陌交通（RoadWeaver）
装了阡陌交通（RoadWeaver）时，它自动生成的道路会被读进来：画在世界地图上、 参与寻路，它连接的村落与小屋成为目的地。和机械动力、MTR 一样，这是一层只读图层： 从你的路网文件里找不到它们，也不随地图导出。用法见 阡陌交通， 配置有五项：
| 键 | 默认值 | 说明 |
|---|---|---|
roadweaver_roads |
true |
整层道路（含路尽头的连接段）的总开关。关掉等于这一层清空，其他功能与图层都不受影响。 |
roadweaver_road_class |
"auto" |
它铺的路按什么等级读。"auto" 就是一律按小路读：
它铺的是土、砂砾与木板，路宽是「铺了几格」，不是「能不能开车」，所以不替它猜车道。
填一个等级名可以强制成那个等级（例如全读成公路）。 |
roadweaver_full_map |
true |
单人存档或把世界「对局域网开放」时，是否直接读它进程内的整个路网， 不必先打开它自己的路网地图（H）。 联机在别人的服务器上时这一项无事可做：只读得到它发给客户端的那一份， 所以那一局要先按一次它的路网地图（H），之后它广播的局部更新会让图层自己更新。 |
roadweaver_structures |
true |
它连接的村落与小屋要不要成为目的地。关掉只是它们不再出现在目的地列表里，道路照旧。 |
roadweaver_routing |
true |
这些路参不参与寻路：步行、驾车（被强制成可开等级时）以及公共交通的步行接驳段。 关掉后照旧画在地图上，只是不参与规划。 |
路口按它自己的说法：两条路在同一个点才算连通，交叉而过、没有共享点位的不算（可能是立交，不猜）。 路尽头的缺口会补一条同等级的直线连接段连到结构，画在地图上、参与寻路、随整层替换，但不写回。 道路、连接段与结构从不写进你自己的路网文件，也不随地图导出。
MTR 集成
| 键 | 默认值 | 说明 |
|---|---|---|
mtr_transit |
true |
是否读取 MTR 的车站与线路，变成问道自己的站点与公共交通线路。 读取是反射的、只在客户端发生，所以没装 MTR 时这一项不做任何事，两个方向都不需要依赖。 MTR 的世界在它自己的服务端上，最基本的一次读取只是玩家附近的那一段窗口； 另外两种读取（自己开图读整张铁路、装了 MTR Map Overlay 读它抓回的整张快照）见下面两项。 线路按类型映射，列车与缆车算铁路、船算水路，其它类型（飞机，或 MTR 以后新加的类型） 不猜，直接不处理。细节见 MTR 集成。 |
mtr_full_map |
true |
自己开图时（单人存档，或把世界「对局域网开放」），是否直接读取 MTR 服务端此刻 正在模拟的整张铁路——全部车站与线路，不受 192 格同步窗口限制。 读取发生在 MTR 自己的线程上，只带回不可变的结果，从不写回 MTR 的数据。 联机在别人的服务器上时这一项无事可做：进程里根本没有那张网络。 |
mtr_map_overlay |
true |
是否读取 MTR Map Overlay（模组 id mtrmap）从服务器抓回并缓存的那份
整张网络快照（每条线、每个车站、每段轨道）。需要客户端与服务器都装了它。
这是三种读取里唯一说得出「每条线走哪几段轨道」的一种，所以由它画出的线路沿着真正的铁路走。
它只读服务器回答过的那份快照，抓不到就什么都不读（不会把 MTR 自己发的那段窗口读两遍）。
它自己的「线路 / 轨道」两个地图开关会被问道记住，见下面的数据文件。 |
mtr_station_merge_blocks |
256（0~4096） |
两个 MTR 车站相距多少格以内算同一个车站（还要同名：忽略大小写与首尾空格）。
MTR 把玩家拖出的每个区域都算一个车站，一个站台一个框建出来的车站会变成多个同名车站；
合并后列表一条、地图一个标记、线路停一次，位置取所有站台的中点。没名字的车站从不合并；
设成 0 就完全按 MTR 原样提供。 |
mtr_auto_route_marks |
true |
MTR 的线路要不要带着自己走的轨道一起进来，作为问道的只读道路。 开启：把这条线实际走的那段 MTR 轨道标成只读的铁路（船线则是水路）， 于是坐这趟车是按 MTR 真正铺的轨道来算的——这些标记从不写进你的路网，也从不可编辑。 关闭：不标记任何轨道，线路的站点改按老规矩去匹配你画的路旁边—— 这正是「这条线本来就走在你已经画好的路或水路上」时想要的答案。 这是没被单独回答过的线路的默认值：线路配置界面里每条 MTR 线路行尾有一个方块可以逐条覆盖， 给过的答案按线记住。逐条设置的用法见 MTR 集成 与 公共交通线路。 |
浏览器地图
/howtogo webmap 会在本机回环地址上开一个小的 HTTP 服务，把当前维度的路网送到浏览器里。
用法、页面上的开关与导出见 浏览器地图；配置里只有两项管它：
| 键 | 默认值 | 说明 |
|---|---|---|
webmap_auto_start |
false |
世界加载后是否自动启动这个服务，而不必等你敲 /howtogo webmap。
它只监听 127.0.0.1 与 ::1 两个回环地址，
配置里没有任何能把它放到局域网上的开关，所以这一项只管「端口是不是提前开着」，
不是关于暴露面的选择。默认关：一个没被要求就开监听端口的模组，会出现在没人想要的防火墙列表里。 |
webmap_port |
7573（1024~65535） |
服务的端口，页面地址形如 http://127.0.0.1:<端口>/。
被占用时依次试后面 9 个，实际绑定的端口写在聊天消息里，所以回退之后书签也不会悄悄失效。
填一个你记得住的数字，而不是一个「碰巧空着」的数字——端口是玩家要亲手敲的东西。 |
日志
日志里有两类东西。一类是警告与错误，以及一次性的事件行（加载 / 保存 / 注册 / 启用、 切换出行方式、到达、偏航重新规划、某个模式回退到步行）——它们一直写，因为每一条都能对上玩家看到的某件事。 另一类是本模组自己的诊断：铁路图层每秒一行、地图每秒一行、MTR 每次读入的统计、 每次规划的路由算术、一条线路被画成直线段的几何报告、线路配置界面的统计、语音在说什么…… 它们是「模组自己怎么在跑」的测量，值得排查时打开，不值得开一整个会话。所以 0.2.1 把它们收进了一个开关：
| 键 | 默认值 | 说明 |
|---|---|---|
debug_log |
false |
是否把本模组自己的诊断写进日志。改完即时生效，不用重开游戏。 关掉时连计数都不做：那些每元素调用的计数器在开关关掉的第一行就返回。 警告与错误不受影响，照旧一直写。 |
0.2.1 同时删掉了一个旧探针：Xaero 地图投影的 P0 测量（RoadDebug，每秒一行
[HowToGo/P0] ... RESIDUAL=...），以及打开它的系统属性 -Dhowtogo.debug。
它只用过一次，量出来的结论已经写进代码注释并由回归测试守着，所以连属性一起删了。
运行时偏好与数据文件
运行时偏好
交通方式、路线偏好和语音开关在「选择目的地」界面里就能点着切换，这些点击写进
config/howtogo/route_preferences.json，重启之后还保留。
这个文件不存在时，以上表的值为准——配置文件是初始值，这个文件是「你上次的选择」。
两者冲突时以这个文件为准，因为它是你后来按的。
想回到配置里的默认行为，删掉 route_preferences.json 即可；
它是按客户端而不是按存档记的，因为你习惯怎么走与在哪个世界无关。
文件都在哪
路网、线路和名字都在 config/howtogo/ 下，首先按世界分开：
单人存档按世界名（sp_<世界名>），多人服务器按服务器地址（mp_<地址>）。
0.2.2 起目录名里的中文按拼音写：sp_新世界 的目录是
sp_xin_shi_jie（0.2.1 及以前是一串下划线），其余非法字符仍各换成一个下划线，
ASCII 世界名原样保留。第一次打开某个世界时会自动整目录改名，升级不用做任何事；
但降级有风险——用 0.2.2 存过档再退回 0.2.1，那个世界的路网会是空的。
坐标只在一个维度里才有意义，所以文件名里还带着维度；
改名、换地址、换电脑时目录怎么跟着变，见 迁移地图数据。
| 路径 | 内容 |
|---|---|
config/howtogo/<存档>/<维度>.json |
这个存档这个维度的道路网络：节点、路段、道路名称、地点与地点类型。 |
config/howtogo/<存档>/<维度>-lines.json |
公共交通线路：线路名、线路类型、按顺序的站点。单独一个文件， 所以它读不回来时你丢的是线路，不是路网。 |
config/howtogo/<存档>/<维度>-rail-names.json |
自动识别铁路的名称。它必须单独放：铁路图层每秒重建、路段 id 每次重排， 所以名字是按「路段两端的坐标」记的，而不是绑在 id 上。 |
config/howtogo/<存档>/.world |
这个目录属于哪个世界（原始世界名）。用来区分清洗后同名的中文世界名： 不带哈希的目录由它记录归属，后来「清洗后同名、名字却不同」的世界才会拿到带短哈希的目录。 导入别人的压缩包时，包里的这条记录会被改写成当前世界，见 迁移地图数据。 |
config/howtogo/mtr_line_marks.json |
MTR 线路逐条的轨道标记开关：在 线路配置界面里 给每条 MTR 线路点过的答案（按 MTR 的线路 id 记），下次进游戏还是上次的选择。 |
config/howtogo/mtr_overlay_toggles.json |
MTR Map Overlay 自己那两个地图开关（「线路」/「轨道」）的记忆： 0.2.2 起问道把它们记在这里，改了立刻保存、下一局恢复成上次的样子。 它自己的配置文件不动；删掉这个文件就不再记（回到「都画」）。 没装那个模组时整个功能不存在。 |
config/howtogo/exports/ |
「地图存档」界面导出的 .zip 默认写在这里，/howtogo export 也一样。
一个包就是当前世界的道路、地点、铁路名称、公共交通线路与附属数据。 |
config/howtogo/backups/ |
导入别人的压缩包、覆盖之前把旧数据整目录备份到这里，文件名带
-backup。它在「可导入的压缩包」列表里单独标黄，
再导入它一次就回到导入之前。 |
config/howtogo/<存档>.replaced-<时间> |
导入时旧目录的去处：新数据先在旁边建好，然后一次改名到位，旧目录改名到这里留着。 确认新数据没问题之后，它是可以删的。 |
config/howtogo/route_preferences.json |
上次选择的交通方式与路线偏好（与存档无关）。 |
config/howtogo/map_filter.json |
地图显示面板的开关、卷起状态与面板位置（与存档无关，是客户端偏好）， 详见 地图显示与缩放。 |
config/howtogo-client.toml |
客户端配置，就是本文上半部分那张表。 |
机械动力、MTR 与阡陌交通的图层是只读的，从不写进这些文件：每次都是从那个模组重新读出来的。 所以你在这些文件里找不到它们的轨道，也不该期待在那里改。
备份、搬家与手工修改
想备份路网，复制整个 config/howtogo/ 目录就够了；换电脑搬家也是同一个目录，
再加上 config/howtogo-client.toml 就能把你的设置一起带走。
反过来，删掉模组的 jar 不会删掉这些文件——路网是你的数据，不是模组的缓存。
搬家要分情况：只改 saves/ 里的存档文件夹名不用动数据；
改了世界名、换了服务器地址，或者复制存档以后想让副本独立，目录名会跟着变，
需要把 JSON 搬到新目录。每种情况的做法见 迁移地图数据。
0.2.2 起还多了一条不用手抄 JSON 的路：/howtogo data 打开「地图存档」界面，
一个按钮把当前世界的道路、地点、铁路名称、公共交通线路与附属数据打成一个
.zip 放进 config/howtogo/exports/，另一个按钮把别人的 .zip 导入回来；
/howtogo export 直接导出，/howtogo import [压缩包] 读指定文件，
压缩包也可以直接拖进界面。导入无视压缩包名与内部目录名，覆盖前有警告并先备份到
config/howtogo/backups/，然后整目录替换而不是合并——
包里没有的维度文件会被删掉。只接受认识的 .json 条目；
没有任何可读数据的包会被拒绝，当前地图不动。完整说明见
迁移地图数据。
数据是客户端本地的：服务器上没有它，别的玩家也没有它。这既是「不用求服主」的原因， 也是「别人看不到你画的路」的原因。
如果你要手工编辑这些 JSON：
- 用 UTF-8 保存，否则中文名字会变成乱码。
- 改坏了最坏的结果是那一个文件读不回来：线路文件读不回来就是「没有线路」， 道路文件读不回来就是「这个维度还没有路」。它不会连累相邻的文件，也不会写坏游戏本体。
- 改之前先复制一份。这些文件是人的数据，手工改动没有校验和，也不会自动备份 （导入压缩包时的自动备份只覆盖导入这一条路）。
面板上的开关（道路等级、地点类型、公共交通线路）存在 map_filter.json 里，
与路网文件分开：你换一个存档，那些开关还是你上次按的样子。