Factorio Blueprint Printer (蓝图自动打印机)

Factorio Blueprint Printer 是一个为《异星工厂》(Factorio) 设计的自动化建造辅助模组。它能够自动检测玩家周围的虚影（Ghosts）、升级规划和拆除规划，并利用玩家背包中的物品自动完成建造、升级或拆除工作。

这就像是一个随身的个人机器人指令平台，但它消耗的是你的背包物品，并不需要建设机器人或机器人指令模块（当然，它也支持与机器人协同工作）。

本模组包含以下核心功能。配置界面可独立开关：自动放置、自动升级、自动拆除、自动插入模块、自动填海。自动开采由拆除快捷按钮统一控制。

• 自动放置 (Auto Place): 自动检测周围的实体虚影，并使用背包中的对应物品进行建造。支持保持物品的健康值和质量（Quality）。
• 自动升级 (Auto Upgrade): 自动检测被升级规划器标记的实体，并尝试使用背包中的高级物品进行替换。旧物品会自动返还到背包。
• 自动拆除 (Auto Deconstruct): 自动移除被红色拆除规划器标记的玩家建筑（如传送带、组装机等）。只操作人物真正够得到的目标；已锁定目标超出触及距离时，会释放它并继续寻找可达目标。
• 自动开采 (Auto Mine): 自动开采被标记为拆除的 树木 和 岩石。
  • 当前行为: 该功能不再是 GUI 独立开关，而是与“自动拆除”绑定，由拆除快捷按钮统一开启或关闭。
• 自动插入模块 (Auto Modules): 放置实体虚影时，按请求的品质和槽位插入背包中已有的插件；缺少的插件请求保留给机器人处理。
• 自动填海 (Auto Landfill): 放置实体虚影时，用背包中的普通品质填海料填平建筑占地内的水面。不会单独处理地砖虚影；单个占地超过 4096 格水面的建筑会跳过。

• 快捷栏双按钮:
  • 蓝图打印机总开关 (fbp-toggle): 控制全部自动操作。关闭时立即停止自动建造、升级、拆除和开采，保留功能勾选；再次开启时恢复所选功能。插模块与填海随自动放置一起暂停。
  • 拆除与自动开采开关 (fbp-deconstruct-toggle): 选择是否自动拆除及开采树木/岩石，仅在打印机总开关开启时运行。
• 配置界面快捷键 (fbp-open-config): 默认 SHIFT + 鼠标左键，用于打开 配置菜单。
• 配置界面: 勾选要启用的具体功能。注意，自动开采不在 GUI 中单独显示，而是跟随拆除状态。

• 打印速度 (Tick间隔): 调整扫描和建造的频率。数值越小速度越快，但可能会增加UPS负载（默认 30 ticks）。
• 扫描半径 (Scan Radius): 工作范围取此半径与玩家实际建造距离中的较小值（默认 100 格，上限 500 格）。从玩家附近开始，按最多 32×32 格的小区域轮询；每类目标每周期最多查询 8 个区域、检查 100 个候选，记住进度继续扫描。缺料或受阻目标会留待下一轮，不再靠倍增扫描数量扩大工作量；移动到新区域、切换地表或调整有效半径后重新扫描。
• 批量放置模式: 为存档兼容而保留，目前两种取值行为一致。每个玩家的每轮工作最多放置 5 个实体、升级 5 个实体。
• 为我启用蓝图打印机: 每个玩家独立的全局开关。如果您暂时不想使用本模组，可以在这里彻底关闭。

每个玩家的开关、扫描半径和调度都绑定其固定的玩家 ID。其他玩家加入或退出不会改变这一绑定。/fbp-check 会显示该 ID，方便排查存档状态与权限：

1. 管理员 (Admin): 始终拥有使用权限（除非自己在设置中关闭）。
2. 普通玩家:
   • 默认情况下，普通玩家可能无法使用（显示 "仅限管理员！"）。
   • 启用方法: 管理员需要在 地图设置 (Map Settings) -> 模组设置 -> 全局 中，勾选 "允许他人使用 (Allow Others)"。
   • 开启该选项后，服务器内的所有玩家均可使用本模组。

Q: 为什么提示 "无物品栏！" (NO INVENTORY!)? A: 模组需要访问玩家的主背包来进行物品交换。如果您处于上帝模式或者某些特殊的控制器状态下，可能无法检测到背包。请切换回正常角色或确保控制器带有背包。

Q: 为什么提示 "蓝图打印机已在您的用户设置中禁用"? A: 请检查 选项 -> 模组设置 -> 个人，确保 "为我启用蓝图打印机" 处于勾选状态。

Q: 为什么提示 "仅限管理员！" (Admin only!)? A: 您当前不是管理员，且服务器未开启 "允许他人使用" 的全局选项。请联系服务器管理员开启。

Q: 遇到未知错误怎么办？ A: 在控制台输入命令 /fbp-check，它会打印出详细的诊断信息（包括您的权限状态、背包状态等），请将这些信息反馈给作者。

推荐在游戏的模组界面搜索 Factorio Blueprint Printer 并安装或更新；游戏会选择与当前 2.0 / 2.1 版本兼容的发行包。也可在 Mod Portal 下载列表 按游戏版本选择 ZIP，直接放入 Factorio 的 mods 文件夹，无需解压。

GitHub 保留以下 0.3.0 历史安装包：

只安装对应游戏版本的一个包，并保留文件名 Factorio_Blueprint_Printer_0.3.0.zip。两个包共用 Lua 源码，区别仅在 info.json 的游戏版本声明。

2.0 包要求至少 2.0.77，以限定本次核对的物品和虚影接口版本；2.1 包沿用同一份运行时代码。

升级前备份存档。模组保留原有存档字段和设置标识；这不代表 2.1 游戏存档可以降级到 2.0。编辑器模式会关闭两个自动化开关。

从模组目录执行（打包也支持从其他工作目录调用脚本）：

py -3 pack_mod.py                                      # 默认生成源码声明的 2.0 包
py -3 pack_mod.py --factorio-version both               # dist/2.0/ 和 dist/2.1/
py -3 pack_mod.py --factorio-version 2.1 --output-dir out
py -3 -m unittest discover -s tests -p "test_*.py"
lua tests/runtime.lua                                 # Lua 5.2 行为回归

打包只使用 Python 标准库，不修改源码中的 info.json，不包含测试、开发工具或旧 ZIP。运行时按职责分为玩家状态、周期调度、建造升级、拆除开采和 GUI；持久状态统一由 scripts/player_state.lua 管理。

在 VS Code 的 Factorio Mod Packages 面板中，选择仓库根目录的 Publish Mod。先提交修改，并通过 Factorio: Set API Key 保存具有 ModPortal: Upload Mods 权限的 API key。发布钩子需要 Python 3；仓库默认使用 Windows 的 py -3。

两个游戏版本共用源码和 Mod 名称，门户版本号按偶数 / 奇数补丁号成对分配：

源码 info.json 保持 factorio_version: "2.0"，补丁号必须为偶数。手动提升主版本或次版本时，将补丁号设为 0。每个包仍使用标准的 Name_Version.zip 文件名。

py -3 publish_mod.py --check  # 构建两份发布包并检查门户版本冲突，不上传

发布包位于 dist/publish/<源码版本>/2.0/ 和 2.1/。FMTK 调用 publish_mod.py --upload，分别上传、核对门户 SHA1，并创建及推送两个 mod-portal-<版本号> 标签；两者成功后才递增源码版本并推送分支。API key 从 FMTK 的环境变量传入，不写入项目文件。

若中途失败，保持源码不变并再次执行 Publish Mod：已上传且目标游戏版本、文件名、SHA1 全部一致的包会跳过。同版本对应不同内容时会停止，需要使用新的版本对。原生 pack_mod.py --factorio-version both 仍用于本地兼容性测试，两包沿用相同源码版本号；门户发布使用 publish_mod.py 分配不同版本号。

模拟玩家回归与游戏实际运行是不同层次的验证。2.0/2.1 的真实加载、存档迁移和 A/B/C 局域网进退应分别记录；缺少对应游戏版本或联机参与者时，保留为未验证。

tests/run_engine.py 可在 2.1 的隔离目录中，用真实角色及物品运行功能场景，并执行旧代码存档生成、升级和重载。它需要本机游戏、Quality（2.1 同时需要 Recycler）、旧源码 ZIP 和一个空输出目录：

py -3 tests/run_engine.py --factorio "路径/factorio.exe" --baseline "旧源码.zip" --output-dir "新的验证目录"

Steam 安装可额外传入 --steam-app-id 427520；启动标识仅写入测试目录。旧源码 ZIP 的根目录应直接包含 control.lua 等源码文件。测试脚本不会安装进发布包。

• 作者: DSLZL
• 目标版本: Factorio 2.0、2.1（分别打包）

祝您工厂建设愉快！