XFE AMS 2.0

XFE AMS 是 Space Engineers 原版编程块采矿舰队系统：自主推进器与陀螺飞控、移动母舰靠泊、按实际库存循环卸货、按总储能计算电量、有限区域探索试钻、手动范围采掘，以及 LCD Sprite 仪表盘。一次构建同时生成简体中文和英文两套脚本，每套包含四个角色；编程块自带屏幕默认显示图形化配置与状态。

矿机分别可以在大气/重力环境和太空作业；单次任务不负责穿越大气层。远程控制可作为位置、速度和姿态测量方块，飞行不使用其自动驾驶航点。系统面向单一刚性网格矿机，设计上限为 16 台。

验收状态：代码编译、MDK 分析、打包及逻辑测试与游戏内验收分开记录。 本仓库不把编译成功解释为实际飞行或多人服务器验证完成。首次部署请按照 游戏内验收清单 在测试存档中完成空载、重载、靠泊和三趟循环测试。

部署结构

表中为中文版；英文版位于相同结构的 dist/en-US/ 目录。选择对应角色的完整脚本粘贴即可，无需向游戏额外安装语言资源。每份脚本首行注明角色，中文主控首行为 // XFE AMS | 舰队主控（母舰） | zh-CN。dist/manifest.json 记录本次八份产物的路径、实际校验角色、语言、字符数和 SHA-256。旧构建留下的 dist/<角色工程>/ 文件不属于本次双语产物，请以清单为准。

脚本类型由所粘贴的文件固定决定，不再配置“角色”。 新模板不生成 角色 / Role，旧配置残留的字段会被忽略，即使值填写错误或中英文值冲突，也不会改变脚本类型或阻止初始化。配置屏显示编号、语言和实际运行参数。原自定义数据不会被整段重写，已有编号、舰队编号、主控编号及方块组继续使用原值。

游戏内仅粘贴各角色 script.cs 内容，不安装 DLL。工程中的 XFEExtension.SpaceEngineers.ScriptingHelper 1.0.3 仅用于开发机的游戏 API 引用；脚本不继承 IProgramBase，不依赖该包在游戏内运行。

世界设置需要允许编程块脚本，舰队之间需要可用的 IGC 无线通信。所有参与方保持相同的“舰队编号”，每个编程块使用不同的“编号”，矿机与标点端的“主控编号”等于主控的“编号”。只有同舰队且协议兼容的数据参与调度。

中文版的自定义数据、运行参数和枚举值均支持中文，以下部署示例以中文版为准。 新生成模板使用“采矿舰队”“主控”“采矿泊位”“基地货仓”等默认名称；旧英文配置和原英文命令继续兼容，已有 CustomData 不会被自动重写。参数及命令完整对照见 中文参数手册。中英文混用时，必须手动统一舰队编号和主控编号；“采矿舰队”与 mining、“主控”与 base 是不同的真实身份，不会按含义自动合并。旧部署可以继续使用原来的英文 ID 和方块组名，不必为翻译而更名。

硬件与建造要求

每台矿机需要：

• 一个可测量速度、重力、质量的驾驶舱或远程控制。
• 能覆盖前后、左右、上下六个方向的推进器和至少一个陀螺。大气推进器有效推力会随环境变化，不能使用地面空载数据代替重载能力。
• 全部朝同一方向的钻头，钻出的孔道必须容纳完整船体与安全间隙。推进器、钻头、控制器和连接器都必须在编程块所在刚性网格上。
• 可共同覆盖运动方向、退出方向与钻孔入口的摄像机。系统按区域选择位置、朝向和充能合适的镜头，合并扫描结果；不要求某一台镜头独自覆盖整个船体。扫描需要充能。
• 至少一块电池、足够容量的货舱、连接器、完整的传送系统。使用氢推进时需要储氢罐；库存中的冰不被当作保证可用的氢燃料。
• 能覆盖作业范围的通信设备。建议添加单独安全看门狗编程块。

不支持子网格推进器、转子/活塞钻具或子网格连接器。不可用“同构造”扫描来代替矿机所属网格，因为连接器会把母舰与矿机临时连成同一构造。矿机库存统计始终仅覆盖本刚性网格，母舰不会被算入载荷。

母舰需要一个船舶控制器、与“泊位方块组”配置一致的连接器组、与“基地货仓组”一致的接收货舱组。中文版新模板默认名称为“采矿泊位”“基地货仓”；旧部署可继续使用 AMS Docks、AMS Cargo。组内受管方块必须在主控的刚性网格上。每个泊位的外侧预留完整的直线进出港通道，避免装饰、太阳能板或其他停泊船侵入；母舰可以移动，但只能在运动窗口满足条件时进出港。

中文版兼容两套默认组名：配置中的“采矿泊位”组不存在时会查找 AMS Docks，“基地货仓”不存在时查找 AMS Cargo，反向同样适用。已经存在的精确名称优先；自定义组名仍须完全匹配。只接管选定组内的母舰本体方块，不自动加入其它用途的连接器，也不改写自定义数据。诊断会分别指出缺失的泊位组和货仓组；缺少泊位的原因也会发送给等待返航的矿机。

从零启动

1. 在开发机运行下方构建命令，把主控、矿机及可选角色对应脚本分别粘贴到编程块并检查编译。
2. 首次编译会在空 CustomData 中生成 INI 模板。修改标识和硬件配置后重新编译以加载配置。配置齐全、硬件自检通过的空中矿机会自动请求返航接港；现有自定义数据不会被模板覆盖。
3. 在母舰创建“采矿泊位”和“基地货仓”方块组，名称与主控自定义数据一致。在主控运行 诊断，确认驾驶舱、泊位和接收库存可用。
4. 默认 [硬件] 自动标定=是：矿机自动初始化，并使用连接器的实际安装位置与朝向完成首次接港；主控暂停派工时仍接受返航，无需先人工连接或逐台运行 标定。连接成功后才保存实际贴合间距和姿态，尚未连接时仍显示“标定=否”。连接器不必与控制器共线。显式暂停或交还控制的矿机需从主控执行 继续 矿机编号；设为 自动标定=否 时，未标定矿机需人工连接后执行 标定 矿机编号。[飞行] 起飞质量=0 在停靠后自动测量本机起飞质量；也可填写覆盖最大预计起飞总质量的正数（kg），用于停靠时检查起飞推力。
5. 校核下节的钻头覆盖和钻尖偏移。安装看门狗时完成其配置和握手。
6. 主控运行 标点 ... 创建手动任务，或 探索 创建有限探索区域；检查矿图和任务数量。
7. 主控运行 启动。日常启停、召回、诊断、重扫和可选手动标定均可从主控发出，无需逐台操作矿机编程块。矿机会等待载荷满足离港阈值、足够能源、有效任务、许可及母舰平稳窗口，满足后自行出港。默认允许整船载荷降到 5% 或以下后离港。

控制器设置示例：

[系统]
编号=矿机01
舰队编号=采矿舰队
主控编号=主控

[硬件]
自动标定=是
; 留空扫描本刚性网格。填写后必须是准确组名/方块名。
方块组=
控制器=矿机驾驶舱
连接器=矿机连接器
; 从钻头中心到有效钻尖的前向距离，单位 m，必须实测。
钻尖偏移=0.5

[飞行]
; 0：停靠时自动测量本机质量。正数：手动指定最大预计起飞总质量（kg）。
起飞质量=0
巡航速度=15
退钻速度=1
安全间距=1
每帧扫描射线=2

[采矿]
目标矿种=铁,镍,钴
钻头覆盖宽度=6
钻头覆盖高度=6
重叠比例=0.15
孔道半径=3
钻进速度=0.5
单趟进尺预算=15

[货物]
载荷返航阈值=0.95
; 允许离港的最大载荷比例；0 恢复严格清空全部待卸矿物。
起飞载荷上限=0.05

[能源]
电量返航阈值=0.25
低氢阈值=0.25
充电目标=0.90
补氢目标=0.90
能源安全系数=1.5
紧急能源余量=0.10
靠泊预留秒数=120

[显示]
方块组=采矿屏幕
屏幕标签=[采矿屏幕]
页面=矿机
内置屏幕=是
内置屏幕页面=配置
字体=默认
每帧绘制屏数=2
离线判定秒数=5
自动翻页=是
轮播间隔秒数=8
手动停留秒数=20

起飞质量=0 时，矿机保持连接，分帧统计本刚性网格的全部方块质量（含装甲）与完整库存质量，库存按世界库存倍率折算；不会为称重主动脱离母舰，也不会把母舰质量加进来。自带屏配置页显示“测量中”或自动测得的 kg 数。测量未完成、库存快照过期或质量无效时保持停靠，不能用 0 kg 绕过推力检查。卸货、补给和船体变化会触发质量更新；重新编译或重扫后重新测量。增换方块、尤其是带库存的方块后，先停靠，再在主控运行 重新扫描 矿机编号 重建硬件列表；周期称重不会自动发现新的库存方块。离港后飞控使用控制器实时报告的物理质量，手动填写的正数也不会冻结飞行中的质量。

整船库存扫描单次限制为 128 个库存、合计 512 个物品堆栈，以保留原子快照并限制执行成本。超限或扫描异常时会自动清理临时扫描结果，保留上一份完整数据，撤销卸空、离港载荷、采样和起飞质量许可；能源更新与退钻返航仍继续执行。修复库存规模或硬件问题后，停靠后在主控运行 重新扫描 矿机编号 解除扫描故障，再完成两次满足当前离港载荷条件的完整扫描。不会自动删除或抛弃真实物品。

母舰最小配置：

[系统]
编号=主控
舰队编号=采矿舰队
主控编号=主控

[舰队]
控制器=母舰驾驶舱
泊位方块组=采矿泊位
基地货仓组=基地货仓
矿机数量上限=16

[采矿]
目标矿种=铁,镍,钴
钻头覆盖宽度=6
钻头覆盖高度=6
重叠比例=0.15
孔道半径=3

[探索]
采样间距=60
扩挖宽度=60
扩挖高度=60
最大深度=100
任务数量上限=2048

[显示]
页面=舰队

钻头覆盖宽度、钻头覆盖高度 表示实际连续有效开挖覆盖，不能只填钻头外观总尺寸。孔道半径 用于空间占用与安全互斥；必须覆盖矿机安全包络。各矿机与主控使用一致的钻孔尺寸，异形/不同尺寸矿机应分别建立舰队。先在低速浅孔中实测孔道尺寸、船体尾部和偏置钻尖，不能靠增大参数跳过硬件问题。

两种采矿模式

手动标点与完整范围采掘

主控可以直接标点；独立标点端粘贴标点终端脚本，设置正确 主控编号 后发送同样的标点请求。

标点 20 15 30
标点 20 15 30 GPS:入口:100:200:300: GPS:向内:100:200:330:

前三个数依次是入口平面宽度、高度、向内深度，单位 m。摄像机方式使用命中位置为入口中心、视线为钻入方向、摄像机上方向为入口平面的上方。GPS 方式要求入口点和向内方向点两个不同坐标；坐标可以包含 0。入口中心与任务区域会冻结在世界坐标中。

摄像机标点只接受行星或小行星表面。可通过 [标点] 摄像机=准确名称 选择摄像机，扫描距离=1000 设置扫描距离。提示摄像机充能不足时，待扫描范围恢复后重发命令。

范围被分成有重叠的平行孔，采用固定蛇形顺序。手动任务会完成规定范围和深度，遇到无目标矿段也继续；安全故障仍会使任务中止或暂停。实际开挖可能略超出几何边界，取决于钻头实际作用体积，不能用于贴近重要设施的精密切削。

自动探索、试钻与指定矿种优先

探索
探索 300
启动

探索 在主控当前位置冻结一个有限区域；标点端的同名命令也使用主控当前位置。默认大气半径 300 m、太空半径 2000 m，可用参数覆盖。大气按地表采样点搜索，太空按有限观察点及方向扫描小行星。

矿机前往观察点时始终朝实际航段飞行，让航行摄像机覆盖前路；大气中保持上方朝向反重力方向。到达并停稳后，再原地转向本次探测方向，检查目标姿态的悬停与制动余量，等待镜头充能并发射探索射线。扫描阶段以已接受的观察位置停驻，不再要求朝侧面挪回更精确的坐标。射线终点仍由冻结的探索任务决定，实际命中位置与方向回传主控。导航避障射线命中的行星或小行星表面也会交给探矿逻辑：若小行星挡在观察点前方，可直接报告实际命中并申请试钻，不必先穿过小行星到点。主控仍核对冻结区域边界并去重，摄像机列表仍仅在初始化或明确重扫时更新。

自动探索不再每扫一条射线就返航。 完成扫描或退出已完成的自动试钻孔后，矿机显示“等待本矿区续派”，主控优先分配同一搜索区的新试钻点，其次安排附近未完成的观察方向。相同观察点的不同扫描方向可以原地连续执行。其它矿机正在占用所需空间时等待，不能把暂时无可用任务算成整个区域完成。返航条件仍包括满载、低电/低氢、动力或通信问题、返航指令，以及本区域已无待执行任务；不自动转去另一个搜索区。手动范围采掘仍沿原流程完成规定孔道。

空中续派会重新核算当前位置到新任务、退钻和返回移动母舰的能源；不套用停靠时的5%离港载荷和90%充电锁存门槛。预算不足时保留新领取任务并返航补给。结果会重发并随存档保留，续派绑定上一任务编号；晚到任务不会撤销暂停、返航或人工接管。更新时同时替换主控和所有矿机脚本，恢复上线后在主控运行 继续，可保留已有探索任务，无需重新创建矿区或逐机标定。

摄像机能判断实体及表面命中，不能透视矿种。系统钻进时每 5 m 比较整船矿物库存增量，识别 目标矿种 指定的矿种，并按列表先后顺序安排已确认矿点。库存内部转运不会被算成新发现。采样时受管制气/加工/抛货会停用；如果仍存在库存损失或无法隔离，会提示采样无效并将未证实的试钻标为受阻，不会推断“这里没有矿”。

默认试钻深度为大气 60 m、太空 40 m，[探索] 试钻深度 可显式设置。发现区的扩挖受 扩挖宽度、扩挖高度、最大深度 和原搜索边界共同限制。连续两圈相邻孔没有目标矿增量后停止扩张。搜索完成后返航等待，不无限增加范围或深度。

[探索] 母舰安全间距=80 将大气观察点沿反重力方向抬高 80 m；太空首个观察点也避开母舰中心，且保持在搜索球内。搜索区域仍以创建时的世界坐标固定。按母舰体积和附近地形增大净空；不把母舰内部当作可到达的观察位置。入孔前执行中心和四周共五点检查，[采矿] 入口高差上限=5 限制新孔入口的地表起伏；已有孔道发现其他船体占用时拒绝钻进。

请区分结果：SurveyEmpty 表示该次扫描没有表面命中；试钻未检出只表示已采样部分没有目标矿增量；“采样完成”不等于已经确定地下无矿；手动任务的“指定范围采掘完成”才表示其计划钻孔全部完成。受阻或无效采样的区域不能当作正常完成。

周转、能源与移动母舰

矿机正常流程为停靠自检、领取任务、离港、飞行、探索/采掘、沿孔轴退钻。自动任务完成后可在矿区续派；需要卸货或补能时再返航、排队、对接、服务后继续任务。满载默认 95%，钻头库存堵塞、低电/低氢、返航预算不足或承载能力不足也会提前返航。保存孔位和实际进尺，卸货后可以从已开挖的孔恢复。

主控按泊位分别预约航道，检查船体包络、泊位轴线和当前位置至进港点的接近路线。互不冲突的多个泊位可以同时进港、出港，也可以一边进港一边出港；同一泊位、距离过近或路线相交的泊位依次放行。紧急低能源请求优先取得可用通道。扩大并行规模需要实际留足泊位间距和进港空间；不是增加一个并发数量就允许船体穿过彼此。

开放空间航线根据舰队的位置、速度、目标和制动力预判冲突，显示“航线交叉，让行”。预约航道优先，普通交叉航线按确定顺序让行；前方静止且位置新鲜的矿机会生成侧向绕行点，仍需摄像机确认绕行路线。过期位置和尚未确认腾空的空间不按超时直接放行。正式对接阶段继续直接沿已预约轴线贴合，由主控阻止其它受管矿机进入冲突路线。

“三次靠泊失败”属于靠泊故障，不能据此判断相机没发现小行星；故障状态本身不会继续执行探索。现在保留最后一次失败的具体原因。确认故障矿机已停稳且遥测新鲜后，主控将其占用缩为实际位置，释放远处未进入的任务和未来进出港路线；其所在泊位或实际船体空间继续受保护，清理离线名单和重载也不会抹掉这份占用。故障不会再占有全队唯一通道。排除原因后在主控运行 继续 矿机编号，保留的矿机端原指令也仍可使用。

开放空间返航与前往接口前方时，矿机会朝实际航段调整姿态，利用整组摄像机检测航路。近似直线的返航航迹点提前衔接，保留原扫描有效范围内的新鲜净空；转弯、真实障碍或扫描证据失效时仍减速。重力环境先检查目标姿态的悬停能力。孔内退钻保持原孔轴，出港保持实际接港时的姿态，直到离开母舰通道。

获得有效进港许可后，矿机直接前往接口前方的引导点，再连续进入对接；已经位于接口前方的矿机就近接入轴线。等待点只在没有可用许可时使用，取得许可后无需先飞到远处等待点、停稳，再返回接口。引导点距离由 [对接] 接近距离 控制（默认30米，至少两倍矿机半径），用于从侧面汇入。前往引导点的途中仍扫描避障，沿轴线到达入口时连续转入正式对接；已在入口以内的矿机就近接入，不向外绕行。近港重启返航会核对新许可后就近进港，不先飞回旧采矿航迹的远端。

“进港对接”全程按两个连接器的实际安装关系控制姿态，使开口相向、上方向一致；自动标定保留连接器中心的对接间距，修正人工停靠时的横向和角度偏差。进入正式对接后关闭摄像机扫描、障碍判断和扫描限速，直接沿预约通道贴合，并清除上一段的绕行目标与扫描等待。许可、遥测、动力与人工接管检查继续生效。诊断显示“直接对接：扫描与避障已关闭 / 指令速度”，不再把旧扫描净空显示为当前对接条件。

已标定的正常直线进港随剩余距离逐步减速，最后3米才采用 最终接近速度（默认0.2m/s）。首次尚未测得贴合间距时，在距连接器中心至少6米、且不小于两倍矿机半径的范围内先稳定低速，再沿接口轴线接近；游戏报告连接器可连接且姿态、相对速度合格时立即尝试锁定，不等待两个方块中心重合。连接状态由官方连接器接口提供。

贴合需横向偏移小于0.15m、姿态误差小于1°、横向速度小于0.1m/s、角速度差小于0.1°/s，连续稳定2秒；可在接近途中累计。进入后采用较宽的退出门限（0.25m、2°、0.2m/s、0.2°/s），避免轻微波动反复重置2秒等待；实际连接仍核对严格对齐与相对速度。超过退出门限时暂停轴向接近、修正姿态后重新取得稳定窗口。两段进港状态都以连续60秒无进展触发退避，持续接近不会因为整段超过旧版4分钟限制而退出。

扫描以待检测区域为单位，按镜头安装位置、朝向、可用距离分配检测工作，把所有镜头的有效结果合并为一轮扫描。某个镜头扫到自身船体时，仅在当前检测点尝试其他镜头，不清空已有的新鲜净空，也不把这个镜头从其他检测点永久排除。例如前方三个镜头中间一个被挡住，左右镜头仍可共同完成扫描；中间镜头在能看见的其他区域仍会被使用。

钻孔入口确认和探索采样同样会在某个镜头命中本机时继续尝试其他镜头；所有镜头都被本机遮挡时保持等待，不报告入口被其他船占用，也不把尚未观察到的区域记为无表面。

近处航点不会把扫描平面强行压到船头旁边。需要时，近处边缘采样点会沿同一检测方向移动到候选镜头的可视深度，最远不超过本轮扫描距离；每个计入结果的点都必须得到游戏 API 允许并实际完成射线检测。扫描可以观察到本段航点之外，但本段可用净空只计算到航点及船体前缘；航点后方的障碍不会被误判为本段必经障碍。不会跳过未完成的检测点并把它计为已扫描。整组镜头都无法完成某个区域的检测、充能不足或实际发现障碍时，诊断才报告相应问题。

远端射线命中障碍时，矿机会继续汇总各区域的检测结果，以最近命中限制可用净空。整轮扫描完成后，可以沿已经确认空出的部分继续接近，并根据船体前缘、制动力与速度余量减速；不会因为远处一次命中就把前面十几米的空路全部清零。新出现的近障碍会立即缩短已有净空，真正挡住船体时仍停车。障碍名称、距船体距离及命中区域会持续显示，直到新的完整扫描确认解除；普通等待扫描显示 N/18 进度，避免下一轮扫描掩盖受阻原因。这个距离是沿当前航向计算的船体余量，不是屏幕标记到玩家的距离。

在主控运行 诊断 矿机编号 可查看“已识别 / 工作 / 当前射线可扫”、扫描方向，以及“联合扫描：已完成 N/18 个区域，M 个镜头参与”。无法形成可用视线时，提示的是整组镜头尚未覆盖的区域，具体镜头的角度或遮挡作为补充诊断。视角问题不会导致扫描距离不断缩短；仅充能不足才缩短，并保持扫描终点在船体前缘之外。

摄像机列表仅在矿机脚本初始化和明确执行硬件重扫时建立，正常飞行期间不定时刷新。增删摄像机后，在安全停靠或暂停状态从主控运行 重新扫描 矿机编号；也可定向执行 初始化 矿机编号，主控不带目标的 初始化 则会清空主控存档。硬件扫描仍遵守本机刚性网格及方块组限制。初始化、硬件重扫和离港准备会启用已受管的镜头及射线充能。摄像机角度、可用距离和射线开关的含义见 官方相机接口。

[采矿] 单趟进尺预算=15 是出发时能源预算中的新增进尺预留，不是孔深上限；续挖还要计入已钻深度的进出成本。作业途中仍按实时能源和载荷决定何时返航，不强制每 15 m 返回。若准备预算已经超过满电/满氢容量，缩短任务距离、分段深度或增大能源容量；不能靠降低安全储备掩盖无法返航的任务。

电量比例按 Σ剩余储能 / Σ最大储能 计算；储氢按储罐容量加权。脚本分别学习巡航、悬停、钻进、返航能耗，并加入退钻、母舰会合、排队与靠泊预算。低电兜底为 25%，预算不足时会更早返航。充电一旦触发会保持到至少 90% 且下一趟预算足够；不需充电时，满足离港载荷条件即可申请离港。小屏 NET 功率正数表示净放电，负数表示净充电；BRAKE 是最弱方向扣除重力后的可用净加速度，单位 m/s²。

卸货包含所有受管矿物，包括石头和冰；不抛石，非矿物补给不作为待卸矿物。主控主动转移到配置的基地接收货仓，也允许基地传送系统抽取。Empty 仍表示连续两次完整扫描确认待卸矿物为 0；离港许可另用 [货物] 起飞载荷上限 判断，默认 0.05：连续两次完整、有效的扫描确认全部受管库存体积占用率 ≤5%，即可继续出港检查。5% 是允许离港的最大载荷，不是至少必须装入 5%；零载荷也满足。保留补给品计入这个体积占用率，母舰库存不计入。

设置 起飞载荷上限=0 可恢复严格清矿模式：全部待卸矿物必须为 0，非矿物补给仍保留。正数阈值必须小于返航载荷 载荷返航阈值。停靠期间主控会继续卸货；达到默认 5% 后无需等剩余矿物全部卸净，也不再仅因这部分残余矿物产生“卸货无进展”告警。基地满仓或传送不通且载荷仍超离港阈值时继续停靠；能源不足、任务无效、航道或母舰窗口不满足也不能起飞，没有“对接若干秒后强制出发”逻辑。修改参数后在停靠状态重新编译使其生效。

靠泊按连接器自身的位置与速度控制，并计算母舰转动导致的连接器线速度。默认许可窗口：连接器速度 ≤5 m/s，母舰角速度 ≤0.2°/s，连接器加速度 ≤0.1 m/s²；最后3米的目标相对速度为0.2 m/s，遥测年龄 ≤0.5 s。远处航行受扫描净空限制；正式对接速度按剩余距离与实时制动力逐步收敛，不把最终低速用于整段30米。参数位于 [对接]：

[对接]
母舰速度上限=5
母舰角速度上限=0.2
母舰加速度上限=0.1
遥测时效上限=0.5
平稳窗口秒数=2
接近距离=30
最终接近速度=0.2
等待点距离=80
等待点间距=20

母舰运动超限、许可失效或遥测过期时，矿机会退出接近并等待；已连接时失联不会主动脱离。默认三次靠泊失败后暂停。无法在剩余能源内追上母舰时需要母舰驾驶员减速或接应，主控不会接管母舰驾驶权。

图形屏幕与命令

编程块自身的第一个显示面（Surface 0）默认加入仪表盘，无需改名或加入方块组，优先显示“配置”参数页。页面包括系统名称、编号、界面语言、状态和当前已生效的配置；参数分页默认自动轮播，也可使用 页面 + / 页面 - 手动查看更多参数。第二个及后续显示面仅在配置了 [屏幕.1] 等节时启用，避免默认在很小的键盘屏上绘制完整仪表盘。

参数页使用更大的字号和高对比度配色，按显示面的实际可见宽度排版：宽屏每页 5 项，名称和值分列；普通屏或竖屏每页 4 项，名称在上、值在下。过长的文本按当前字体实际宽度省略，保持字号，不再为塞入整段文字而缩小。完整参数仍可在编程块 CustomData 中查看。此调整针对“配置”页，其他仪表盘页面保留原布局；脚本不能提高游戏显示面本身的纹理分辨率，实际中文字形和可读性仍需游戏内确认。

在编程块 CustomData 的 [显示] 中设置 内置屏幕页面=矿机 可让自带屏默认显示单机状态，设置 内置屏幕=否 可关闭自带屏托管。编程块自身的 [屏幕] 页面=... 可覆盖默认页；启用=否 优先关闭该显示面。配置页只读，修改 CustomData 后在停靠状态重新编译，屏幕会显示新生效的值；主控不带目标的 初始化 会清空旧存档并加载配置；只更新硬件列表请用 重新扫描。

自动翻页默认开启：每个屏幕独立计时，每 8 秒循环切换当前页面类型的子页，包括参数分页、舰队列表、未绑定的矿机列表和不同矿区；不会自动从参数页切到舰队等其它页面类型。设置了 绑定矿机=矿机01 的单机屏始终显示该矿机，只有一页时保持当前内容。屏幕底部用进度条和圆点标示轮播进度与当前子页。

在 [显示] 中可设置 自动翻页=否 关闭轮播，轮播间隔秒数=8 调整停留秒数（2～120），手动停留秒数=20 调整手动操作后的暂停秒数（0～300）。每个 [屏幕] 或 [屏幕.N] 节可用同名字段覆盖全局值。手动切页后，默认暂停 20 秒，再开始完整的 8 秒停留计时，下一次自动翻页约在操作后 28 秒发生；页面 停止 可持续停住查看，页面 播放 从当前子页重新计时。这两个命令只改变本次运行状态，重新编译后按配置恢复；永久关闭使用 自动翻页=否。轮播沿用屏幕绘制调度，不改变飞控更新频率。

已有部署更新显示效果时，先确认矿机停靠，再用重新生成的同语言、同角色 script.cs 替换编程块脚本并编译。运行 页面 配置 查看大字参数页，页面 + / 页面 - 翻页，页面 自动 恢复各屏自己的页面绑定、首个子页及配置中的轮播设置。现有 CustomData 无需添加新字段，缺省即启用轮播。

将 LCD/驾驶舱加入本机配置的屏幕组，或在方块名加入配置的屏幕标签。中文版新模板标签为 [采矿屏幕]，可使用“采矿屏幕”组；旧部署可继续使用 AMS Screens / [AMS LCD]。同一屏只能由一个脚本负责。屏幕 CustomData 示例：

[屏幕]
页面=舰队
; 单机页可绑定其它矿机；留空在矿机上默认显示自己。
绑定矿机=
; 可选：覆盖本编程块 [显示] 的轮播设置。
自动翻页=是
轮播间隔秒数=8
手动停留秒数=20

; 驾驶舱的第二个面；第三个面使用 屏幕.2，以此类推。
[屏幕.1]
页面=矿机
绑定矿机=矿机01
启用=是

离线数据保留并标注“离线”/OFFLINE，舰队列表显示数据年龄，不把最后已知状态当成实时状态。参数页和矿区页适配屏幕可见宽度，其他页面按原有比例居中缩放。默认每 0.5 s 最多绘制 2 个屏幕，多个屏幕轮转以保留飞控预算；设置 每帧绘制屏数 可调整吞吐。矿图单帧最多绘制 400 个孔位，统计仍覆盖当前矿区全部任务。图形按钮不是触摸控件，使用快捷栏、按钮板或编程块参数操作。字体使用 [显示] 字体=默认；目标游戏版本的中文字体覆盖及小屏排版仍需要游戏内验收。

主控运行 页面 矿区 可查看探索地图。蓝格表示实际射线经过该投影位置，未执行、仅预约和无有效扫描数据的受阻任务不会填亮；命中后的射线不会延伸到目标后方。格内仍有未扫描空间，不能将格子或扫描完成比例当作整片空间已排除障碍。太空地图使用冻结搜索区的参考平面；大气探索使用地表采样平面，投影可能重叠不同深度的位置。

黄色框为已发现小行星的世界包围盒在该平面的投影，A1 等为本矿区的显示编号。旁边显示估算投影面积，底部显示去重数量及面积合计，单位自动使用 m2/km2；它不是实际表面积、矿藏面积或可采矿量。尺寸来自原版相机返回的 实体世界包围盒，不从单次表面命中臆测整颗形状。每页显示8颗小行星明细，超过后随现有轮播切页，扫描轨迹及总数保持完整。矿机 ID 与小行星面积使用错开的标签和引线；红色表示离线或故障矿机，ID前的 * 表示其位置在当前地图之外。

主控和所有矿机需同时更新才能收到完整的射线与尺寸数据。新数据随任务存档保留；旧任务中的已知表面点仍可显示，但缺少尺寸时标为 ?/大小未知，后续实测再补全，不把未知面积算作已测面积。清空任务也会清空对应地图记录。矿机本地矿区页仍显示自己的任务，完整探索地图由主控绘制。

表中的“矿机编号”要替换为该机配置的实际编号，例如在主控依次运行 诊断 深空工业1号、返航 深空工业1号。编号包含空格时，动词后的剩余文本作为完整编号，也可加双引号。上述单机操作均接受“全部”或 all/* 指定在线矿机；不向离线矿机排队发送一次性维护操作，离线安全占用继续保留。原矿机端英文命令仍然可用，中文版也可直接使用中文。

暂停和交还控制不会被自动初始化或标定撤销。返航指令停止采矿，但保留接港导航；返航或对接期间重新编译后，矿机会自动重新获取母舰位姿和许可再接港，无需重复下令。完成维修或人工接应后，在主控运行 继续 矿机编号；人工仍在驾驶时，脚本不会夺取驾驶权。诊断 全部 的详细回包可能依次更新主控输出；定位单台故障时使用定向诊断最清楚。

要清理改名后留下的旧矿机条目，等待主控初始化或当前格式存档恢复完成，并让需要保留的矿机重新显示在线，然后在舰队主控编程块的运行参数中输入 清理离线矿机，点击运行一次。它采用与屏幕相同的离线判断：超过 [显示] 离线判定秒数 未收到遥测，默认超过 5 秒；恰好 5 秒仍在线。命令只删除当时离线的注册名单和相关缓存，不修改在线矿机、当前任务或运行开关。恢复期间不会执行该命令。

普通失联矿机的任务归属、未知孔道或泊位通道占用会继续保留；清理不会挪动在线矿机的等待点，也不复用尚未确认腾空的等待槽位。已分配且尚未结束的任务总数仍限制为 16：保留的未知任务同样计入，达到上限时新矿机可以登记，但需要等待已有任务归属得到确认和释放后才能派工。原矿机后来恢复有效遥测时会重新登记；清理离线矿机 不是永久拉黑，也不执行 清空任务。

对于改名后的已停靠矿机，主控会核实：新旧 ID 来自同一个非零编程块地址、新 ID 当前在线、主控连接器实际连接这台矿机。三项都满足时，才释放旧 ID 的任务归属、孔道和泊位占用，避免改名后卡住调度；已有任务进度保留，后续可重新派发。先清旧名单、随后新 ID 才登记的情况也会在真实接港后处理。仅有相同名字、连接状态上报或过期遥测均不能触发这个处理，标定与身份存档仍不自动合并。

舰队身份由矿机配置的 [系统] 编号（旧键为 [System] Id）决定，修改编程块方块名称不会改变身份。需要修改编号时，应先停靠并确认原任务与通道已安全处理，再修改配置、重新编译，按新身份重新登记。原 ID 的存档不匹配时，不会自动迁移原来的标定或任务状态；系统也不会自动把新旧 ID 合并。解决身份存档问题并初始化成功后，真实接港会自动重新标定。新身份正常上线后，可在主控运行 清理离线矿机 清理已离线的旧条目。

如果旧名单已占满 16 个注册名额，新 ID 暂时无法上线，可先等旧 ID 显示离线，运行 清理离线矿机 腾出名额；新 ID 后续上报遥测时会再次尝试登记。旧身份仍有未知占用时，系统会保留原编程块地址，防止另一台矿机复用相同 ID 后冒领旧任务或释放旧通道。

要放弃当前矿区并重新规划，先等待初始化或当前格式存档恢复完成，再在舰队主控编程块的运行参数中输入 清空任务，点击运行一次。恢复期间不会执行此命令；需先读完原存档，才能保留未知矿机和航道占用。它是一次性命令，不是需要写进配置的开机清空开关；正常重新编译或载入不会再次清除后来创建的任务。此操作删除当前任务、采样进度和矿区，不能通过 继续 恢复。

正在孔内的矿机保留退出所需的孔轴和位置，关闭钻头后原轴退钻、返航；进出港中的矿机继续按安全通道处理，停靠矿机继续卸货和补能。人工接管仍优先，清空命令不会夺取驾驶权。失联矿机及尚未离开的孔道、泊位通道仍保留占用，不能因为任务列表清空就将相同空间立即派给别的矿机；取消重试、晚到旧任务或重新编译也不能使被清除的任务复活。

清空后，在主控依次运行新的 探索 半径 或 标点 ...，然后运行 启动。取消按矿机逐台确认：必须收到该机的新鲜取消确认，并核实它已实际连接母舰，才允许它领取新任务。已经确认的矿机可在载荷、能源和航道条件满足后先行出港，为其他返航矿机腾出泊位，不要求所有矿机同时停靠。失联矿机需重新联机并回港确认；它的未知占用继续保留，其他矿机只能领取不冲突的任务。返航期间重新编译会自动重新申请接港；主动暂停或人工接管的矿机，在主控运行 继续 矿机编号 恢复；不需要逐台进入矿机编程块。若只是暂时回港并打算续挖原任务，应使用 全部返航。

看门狗、异常与恢复

屏幕提示“所用指令超过 50000 个限值”表示一次执行的计算量超限，不是日志、任务数或脚本文本容量已满。运行时指令计数由游戏管理，脚本没有清零接口；正常结束当前帧后，下一次执行会获得新的预算。系统通过检查剩余预算、分批处理后台工作来提前让出执行；清理仅针对可重新生成的临时显示数据，不删除配置、采矿任务、进尺、占用许可或完整存档。

若已经出现截图中的“脚本执行终止”，当前业务脚本已无法继续执行自动清理。需要替换为修复后的对应角色脚本并重新编译；仅清空屏幕、运行 初始化 或反复点击运行不能恢复已终止的实例。这与 Keen 官方公开的编程块终止处理 和 只读运行时计数接口 一致。两份链接是官方历史源码；当前游戏中的指令峰值仍需实测。

业务脚本因异常、用户停用或电源中断而完全停止后，无法继续执行自身清理代码。可在矿机同一刚性网格安装独立看门狗；它在心跳中断后关闭钻头、清除推进器/陀螺覆盖并恢复阻尼，故障锁定后需要明确握手。看门狗自己同样需要供电和运行机会，不能修复缺失推进器或抵消不足的推力。

粘贴安全看门狗脚本，在其 [系统] 中配置 编号=矿机01看门狗、相同“舰队编号”，并填写 [看门狗] 业务编程块编号=矿机01、超时秒数=3；矿机配置 [看门狗] 启用=是、编号=矿机01看门狗。业务脚本运行后，在独立看门狗执行 布防，再在主控执行 继续 矿机01。看门狗只接受同刚性网格业务编程块的心跳；无新鲜心跳不能布防。可用 触发保护 手动触发清理。业务脚本重启后必须重新布防，恢复存档不会自动重新布防。

采矿业务脚本在正常运行中检测人工接管、关键硬件损坏、无进展、能源不足及失联。孔内优先沿原轴倒退，不先转头横穿未开挖矿体。失联矿机占用保持为未知状态，主控不把其孔道直接分配给另一台矿机。

Storage 保存任务、孔深、标定、能耗学习和充电锁存等状态。重新编译/载入后重新确认硬件、实际连接、母舰信息和许可，才恢复动作。改变矿机“编号”或换成另一种脚本会使原存档不匹配；内部仍保留脚本类型以检查存档归属，这不是配置参数。不要在未确认实际飞船位置之前通过编辑存档清除占用。

主控按独立记录分帧生成任务检查点，完成后才替换 Storage；保存回调保留最近完整检查点。恢复同样分批读取记录，恢复完成前暂停调度和任务执行，避免一次解析整个大型 INI 导致再次超限。正在保存期间的任务结果和占用会补写，重载后所有矿机先视为遥测过期，已有航道占用保留，但旧许可令牌失效。独立标点请求还保留最近 128 个回执，避免重发导致重复创建矿区。

在舰队主控编程块运行不带目标的 初始化（英文 init），立即删除全部历史 Storage 和内存中的任务、进尺、矿区、扫描/发现记录、矿机名单、占用许可、等待队列、消息重试和事件缓存；保留 CustomData 配置并重新读取硬件。命令在存档恢复中、恢复失败或旧档过大时也优先生效，不解析、不迁移旧数据。清空后即写入新的空状态标记，立即保存或重新编译也不会恢复旧任务。初始化完成后保持暂停，重新创建 探索 或 标点 任务，再运行 启动。

本版已删除旧 INI 主控存档迁移。普通重新编译/载入只恢复当前记录格式；遇到旧格式或损坏存档会暂停并提示，直到在主控运行 初始化 清空。无需删除自定义数据，也无需修改编号。需要保留当前格式数据时，修复后重新编译；初始化 的含义是清空，不能用于无损重试。

主控和矿机脚本需一起更新，可选标点终端也使用本版。重置消息使在线矿机取消旧任务、关钻并重新申请返航许可；孔内保留退出所需的孔道数据直到安全退钻，人工接管保持优先，已连接矿机保持连接。每次重置使用新的任务批次，迟到的旧派工、扫描结果和许可不能恢复已清空的数据；离线矿机重连后会收到新批次并取消旧任务。在线矿机收到新遥测后重新进入名单属于正常登记，不是恢复旧存档。矿机侧的标定、能源学习和硬件配置保留。

三个清理命令的范围不同：初始化 清空主控全部旧数据；清空任务 保留矿机名单及尚未确认撤离的空间占用；清理离线矿机 只删除离线名单与缓存。普通硬件更新用 重新扫描。矿机侧原 初始化 和主控定向 初始化 矿机编号 仍用于硬件重扫。

旧版“等待许可”状态现称“进港等候”，包含前往等待点、等候航道授权和姿态速度同步。主控的“航道：某矿机 对接”表示航道已预约给它，不证明它已收到并核对当前许可。矿机诊断分别显示“采矿任务确认”和“航道许可”：清空任务 后，返航矿机的采矿任务确认可以为否，不阻止使用有效航道对接；取消确认会在真实接港后完成。

需要人工接应时，在主控运行 交还控制 矿机编号，人工连接到主控受管泊位，然后在主控运行 继续 矿机编号。这会明确结束人工接管并处理取消任务的接港确认；仅连接或自动标定不会擅自结束人工控制。若要全舰队恢复，在主控运行 启动。更新脚本或加装摄像机后的验证在安全停靠状态进行。

构建、测试与开发

需要 .NET SDK 9 或更新版本、.NET Framework 4.8 编译目标，以及可从 PATH 调用的 PowerShell 7（pwsh，用于语言资源校验与生成）。当前固定使用 MDK2 PbAnalyzers 2.2.0、PbPackager 2.2.11。NuGet 游戏 API 引用来自已有 ScriptingHelper 包，所以无需为本仓库填写本机游戏安装目录；这仍需要在目标游戏版本编译检查兼容性。MDK2 官方安装文档

# 默认：校验资源、生成中英各四个角色、校验打包文本、分别运行两种语言的测试
./build.ps1

# 仅打包开发中的代码，最终验收不使用该参数跳过测试
./build.ps1 -SkipTests

# IDE/单工程默认生成中文；完整交付使用上面的 build.ps1 同时生成两套
dotnet build AutoMiningFleet/AutoMiningFleet.csproj -c Release
# 单独调试英文版
dotnet build AutoMiningFleet/AutoMiningFleet.csproj -c Release -p:ScriptLanguage=en-US

工程按角色选择源码并定义 MINER/FLEET/MARKER/WATCHDOG 符号；每个项目有独立的 obj 目录。共享模块包括核心数据、INI 配置、版本化 IGC 协议、存储和显示。矿机额外包含飞控、硬件、资源和状态机；主控额外包含规划、调度和标点。源码限制 C# 6，禁用隐式 using 和 Nullable，目标为 x64。

参数页只编译当前脚本角色需要的配置行，通用 INI 读写复用公共函数；英文提示采用适合屏幕阅读的简短表达，以控制新增舰队功能后的导出长度。

MDK2 将多个 partial Program 源文件压缩并分别导出到 dist/zh-CN 和 dist/en-US。build.ps1 会拒绝打包失败、缺失/过期产物、语言/品牌不符、超过编程块 100000 字符限制或残留外部 Helper/远控航点导航的产物；还会使用游戏默认命名空间对八份导出文本逐一再次编译，防止项目内有效的 using 被打包移除后造成粘贴失败。随后运行 tools/Verify-PackedRole.cs，从已压缩产物实际执行脚本类型选择、缺省配置、本地化模板和已有配置，确认模板不再生成角色字段、旧角色字段不能覆盖编译类型；实际类型与导出工程不符就终止构建，不发布成功清单。该检查器只在开发机运行，不写入游戏脚本。两种语言的逻辑与界面测试分别记录在 TestResults/zh-CN.trx 和 TestResults/en-US.trx。dist 是生成物，修改后重新构建，不手改压缩脚本。测试覆盖细项及实机通过记录见 验收文档。

完整探索绘图仅编入主控；共享 Data 包装重复的引擎类型调用，局部变量只在推断类型一致时使用 var，不含预处理条件分支的单返回成员可使用 C# 6 表达式语法，以控制导出长度。含 #if 的成员必须保留全部角色分支；这些共享改动同时接受完整双语回归与八份导出角色检查。

可复用语言资源

文本存放在 Localization/ 的 UTF-8 JSON 文件中，按 common、miner、fleet、display 等语义分组；每组均有 .zh-CN.json 和 .en-US.json。parameters 保存配置节、参数名、枚举、命令和新部署默认名称的可复用映射，fleetoperations 保存集中控制提示。相同语义使用同一资源键，带变量的文本使用 {0}、{1} 等占位符；字面大括号写作 {{ / }}。修改翻译时同时保持两份资源的键和占位符一致。

tools/Generate-Localization.ps1 在构建时校验缺项、重复键、非法格式和占位符不一致，再为当前角色/语言生成独立的 C# 常量。四个角色共享资源；MDK 只保留该脚本实际使用的常量。生成文件放在 .generated/<工程>/<语言>/，不会覆盖资源原文，也不会把两套字典同时装入同一个游戏脚本。游戏内没有文件读取或 ResourceManager 依赖。

系统名称统一为 XFE AMS，源码工程名保留以兼容已有构建。中文配置、矿种名称和运行参数在用户输入边界转换为统一内部标识；通信协议、任务 ID 和存档标识保持一致。中文版接受原英文别名，英文版继续提供英文模板。用户自行设置的编号、真实方块名称和组名保持原文，系统不会把“主控”与 base 等名字当成相同身份。

两种版本可以通信，但必须统一实际舰队编号/主控编号，远端自由文本告警保留发送端语言；希望界面语言完全一致时，同一舰队使用同一种语言的全套脚本。切换语言请停靠后替换对应角色脚本并核对配置；原英文配置在中文版仍有效，现有 CustomData 的正文和注释不会被自动翻译或覆盖。若将中文配置切换到英文版，按对照表恢复英文节名、参数名及枚举值，保留实际 ID 和方块名称。

旧版升级流程：替换主控与每台矿机脚本、核对配置与编号，在主控运行 初始化 清空历史主控数据，再创建新任务。1.x 的布尔状态、远控航点以及 XFE AMS 2.0 早期 INI 主控任务存档均不迁移；1.x 矿机升级仍需先人工停靠，再完成首次自动标定。