XFE AMS 2.0

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

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

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

部署结构

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

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

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

硬件与建造要求

每台矿机需要：

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

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

母舰需要一个船舶控制器、AMS Docks 连接器组、AMS Cargo 接收货舱组。组内受管方块必须在主控的刚性网格上。每个泊位的外侧预留完整的直线进出港通道，避免装饰、太阳能板或其他停泊船侵入；母舰可以移动，但只能在运动窗口满足条件时进出港。

从零启动

1. 在开发机运行下方构建命令，把主控、矿机及可选角色对应脚本分别粘贴到编程块并检查编译。
2. 首次编译会在空 CustomData 中生成 INI 模板。修改标识和硬件配置后，在已连接状态重新编译以加载配置。现有自定义数据不会被模板覆盖。
3. 在母舰创建 AMS Docks 和 AMS Cargo 方块组。检查主控 diagnose 输出，确认驾驶舱、泊位和接收库存可用。
4. 将矿机人工连接到目标泊位；[Flight] DepartureMass=0（默认）会自动测量本机起飞质量，等待测量完成后运行 diagnose、calibrate。也可填写正数，作为停靠时检查起飞推力的手动质量（kg），应覆盖最大预计起飞总质量。标定保存连接器与控制参考的相对位置和姿态，因此不要求连接器与控制器共线。
5. 校核下节的钻头覆盖和钻尖偏移。安装看门狗时完成其配置和握手。
6. 主控运行 mark ... 创建手动任务，或 survey 创建有限探索区域；检查矿图和任务数量。
7. 主控运行 start，需要时在矿机运行 start/resume。矿机会等待卸空、足够能源、有效任务、许可及母舰平稳窗口，满足后自行出港。

控制器设置示例：

[System]
Role=miner
Id=miner-01
FleetId=mining
BaseId=base

[Hardware]
; 留空扫描本刚性网格。填写后必须是准确组名/方块名。
Group=
Controller=Miner Cockpit
Connector=Miner Connector
; 从钻头中心到有效钻尖的前向距离，单位 m，必须实测。
DrillTipOffset=0.5

[Flight]
; 0：停靠时自动测量本机质量。正数：手动指定最大预计起飞总质量（kg）。
DepartureMass=0
CruiseSpeed=15
RetreatSpeed=1
Clearance=1
RaysPerTick=2

[Mining]
TargetOres=Iron,Nickel,Cobalt
FootprintWidth=6
FootprintHeight=6
Overlap=0.15
HoleRadius=3
DrillSpeed=0.5
SortieDepthBudget=15

[Cargo]
ReturnFill=0.95

[Energy]
ReturnBattery=0.25
LowHydrogen=0.25
ChargeTarget=0.90
HydrogenTarget=0.90
ReserveFactor=1.5
EmergencyReserve=0.10
DockReserveSeconds=120

[Display]
Group=AMS Screens
Tag=[AMS LCD]
Page=miner
BuiltIn=true
BuiltInPage=config
Font=Debug
ScreensPerTick=2
OfflineSeconds=5
AutoPage=true
PageInterval=8
ManualHoldSeconds=20

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

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

母舰最小配置：

[System]
Role=fleet
Id=base
FleetId=mining
BaseId=base

[Fleet]
Controller=Base Cockpit
DockGroup=AMS Docks
CargoGroup=AMS Cargo
MaxMiners=16

[Mining]
TargetOres=Iron,Nickel,Cobalt
FootprintWidth=6
FootprintHeight=6
Overlap=0.15
HoleRadius=3

[Survey]
Spacing=60
ExpansionWidth=60
ExpansionHeight=60
MaxDepth=100
MaxJobs=2048

[Display]
Page=fleet

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

两种采矿模式

手动标点与完整范围采掘

主控可以直接标点；独立标点端设置 Role=marker 和正确 BaseId 后发送同样的标点请求。

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

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

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

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

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

survey
survey 300
start

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

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

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

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

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

周转、能源与移动母舰

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

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

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

卸货包含所有受管矿物，包括石头和冰；不抛石，非矿物补给不作为待卸矿物。主控主动转移到 AMS Cargo，也允许基地传送系统抽取。矿机连续两次完整库存扫描确认待卸矿物为 0 后才完成卸货。满仓、传送不通、补能无进展时保持停靠并报告原因，没有“对接若干秒后强制出发”逻辑。

靠泊按连接器自身的位置与速度控制，并计算母舰转动导致的连接器线速度。默认许可窗口：连接器速度 ≤5 m/s，母舰角速度 ≤0.2°/s，连接器加速度 ≤0.1 m/s²；最终接近速度 ≤0.2 m/s，遥测年龄 ≤0.5 s。参数位于 [Dock]：

[Dock]
MaxBaseSpeed=5
MaxBaseAngularDeg=0.2
MaxBaseAcceleration=0.1
MaxTelemetryAge=0.5
StableSeconds=2
ApproachDistance=30
FinalSpeed=0.2
WaitingDistance=80
WaitingSpacing=20

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

图形屏幕与命令

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

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

在编程块 CustomData 的 [Display] 中设置 BuiltInPage=miner 可让自带屏默认显示单机状态，设置 BuiltIn=false 可关闭自带屏托管。编程块自身的 [AMS.Screen] Page=... 可覆盖默认页；Enabled=false 优先关闭该显示面。配置页只读，修改 CustomData 后在停靠状态重新编译，屏幕会显示新生效的值；init 仍只负责初始化失败后的重试或运行中的重扫。

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

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

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

将 LCD/驾驶舱加入本机 AMS Screens 组，或在方块名加入 [AMS LCD]。同一屏只能由一个脚本负责。屏幕 CustomData 示例：

[AMS.Screen]
Page=fleet
; 单机页可绑定其它矿机；留空在矿机上默认显示自己。
Miner=
; 可选：覆盖本编程块 [Display] 的轮播设置。
AutoPage=true
PageInterval=8
ManualHoldSeconds=20

; 驾驶舱的第二个面；第三个面使用 AMS.Screen.2，以此类推。
[AMS.Screen.1]
Page=miner
Miner=miner-01
Enabled=true

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

看门狗、异常与恢复

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

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

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

看门狗的 System.Role=watchdog、Id=miner-01-watchdog、相同 FleetId，并填写 [Watchdog] BusinessId=miner-01、Timeout=3；矿机配置 [Watchdog] Enabled=true、Id=miner-01-watchdog。业务脚本运行后，在看门狗执行 arm，再在矿机执行 resume。看门狗只接受同刚性网格业务编程块的心跳；无新鲜心跳不能布防。可用 trip 手动触发清理。业务脚本重启后必须重新 arm，恢复存档不会自动重新布防。

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

Storage 保存任务、孔深、标定、能耗学习和充电锁存等状态。重新编译/载入后重新确认硬件、实际连接、母舰信息和许可，才恢复动作。改变矿机 Id 或角色会使原存档不匹配。不要在未确认实际飞船位置之前通过编辑存档清除占用。

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

XFE AMS 2.0 早期主控使用单份 INI 保存任务。更新主控脚本并重新编译后，系统会自动分帧迁移旧 INI 存档，包含超过 32768 字符的大型旧档；迁移期间暂停调度，屏幕显示恢复状态。旧任务、实际进尺、矿区、发现记录和未知占用保留，只有新版完整检查点生成成功后才替换原 Storage。迁移完成后主控保持暂停，请核对矿机实际位置和在线状态，再在主控执行 start；不必重新运行 survey 或创建重复任务。

若仍看到旧版本的“旧格式存档过大”提示，请替换舰队主控脚本并重新编译。这个问题属于编程块内部的 Storage，不是 CustomData 配置错误；清空自定义数据不能解决。若迁移过程中发现存档损坏或角色/ID 不匹配，系统会保留原文并给出存档错误，不自动删档。重新编译或运行 init 可以在原因修复后重试；不要通过改变 ID 绕过已有任务的占用。建议升级前备份世界存档。

构建、测试与开发

需要 .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。

MDK2 将多个 partial Program 源文件压缩并分别导出到 dist/zh-CN 和 dist/en-US。build.ps1 会拒绝打包失败、缺失/过期产物、语言/品牌不符、超过编程块 100000 字符限制或残留外部 Helper/远控航点导航的产物；还会使用游戏默认命名空间对八份导出文本逐一再次编译，防止项目内有效的 using 被打包移除后造成粘贴失败。两种语言的逻辑与界面测试分别记录在 TestResults/zh-CN.trx 和 TestResults/en-US.trx。dist 是生成物，修改后重新构建，不手改压缩脚本。测试覆盖细项及实机通过记录见 验收文档。

可复用语言资源

文本存放在 Localization/ 的 UTF-8 JSON 文件中，按 common、miner、fleet、display 分组；每组均有 .zh-CN.json 和 .en-US.json。相同语义使用同一资源键，带变量的文本使用 {0}、{1} 等占位符；字面大括号写作 {{ / }}。修改翻译时同时保持两份资源的键和占位符一致。

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

系统名称统一为 XFE AMS，源码工程名保留以兼容已有构建。命令、INI 键、方块组名、矿种配置 ID（如 Iron）、任务结果标识及通信协议不随语言改变；中文只改变呈现文本。两种版本可通信，但远端发送的自由文本告警保留发送端语言；希望界面语言完全一致时，同一舰队使用同一种语言的全套脚本。切换语言请停靠后替换对应角色脚本；现有 CustomData 的注释不会被自动翻译或覆盖。

1.x 旧版升级流程：召回全部矿机、人工确认停靠、保存测试存档、替换主控与每台矿机脚本、更新配置与 ID、重新标定、重新创建任务。1.x 的布尔状态及远控航点不直接迁移为空中恢复点；XFE AMS 2.0 早期 INI 任务存档使用上文的自动迁移流程，保留原任务。