AmmoToBox

# AmmoToBox
**厌倦了手动把几百发散装子弹一发发塞进弹药箱？交给 AmmoToBox 来帮你！**

AmmoToBox 是一款为 [永恒枪械工坊：零 (TaCZ)](https://www.curseforge.com/minecraft/mc-mods/timeless-and-classics-zero) 打造的轻量级实用模组。它可以让你立即将散装弹药装入弹药箱，并自动合成缺少的子弹。

## ✨ 功能特色
* **⚡ 一键打包**：扫描主背包、**潜影盒**，甚至**精妙背包**，立即提取散装弹药。
* **⚙️ 智能自动合成**：自动读取 TaCZ 枪械工作台配方。只要材料充足，就会自动合成子弹并直接装入弹药箱。
* **🖥️ 交互式设置界面**：按 `V` 键打开可视化界面。玩家可以切换自动合成功能，也可以自由排除特定容器（如潜影盒或背包），避免扫描并保护资源。（若未安装精妙背包，界面会自动隐藏相关选项。）
* **🛡️ 快照校验，安全可靠**：采用“先扫描、再验证、最后扣除”的机制，并设有溢出保护，可彻底避免物品复制或吞物品问题。扣除顺序经过严格硬编码，以确保安全。
* **🔧 配置动态更新**：服务器服主可以随时修改 `.toml` 文件中的设置，无需重启服务器！（如果部分独立服务器没有立即更新，只需输入一次 `/reload`。）

## 🎮 使用方法
1. **设置弹药类型**：先手动往空弹药箱里放入至少一发子弹。
2. **一键打包**：主手拿着弹药箱时，**潜行（Shift）+ 右键**。
3. **玩家设置**：按 **`V`** 键打开设置面板，切换自动合成功能或排除容器。

## 🔧 服务器配置
配置文件位于 `serverconfig/ammotobox-server.toml`：
– `enableAutoCraft`：全局启用或禁用自动合成。
– `autoCraftDefault`：新玩家的默认自动合成状态。
– `maxCraftsPerOperation`：每次操作的最大合成批次。
– `ammoBoxMaxCount`：每个弹药箱的最大容量。
– `compatShulkerBox`：是否允许从潜影盒中提取物品。
– `compatSophisticatedBackpacks`：是否允许从精妙背包中提取物品。*（即使未安装该模组，也可以安全地设为 true。）*

## 📌 前置依赖
– **必需**：[永恒枪械工坊：零 (TaCZ)](https://www.curseforge.com/minecraft/mc-mods/timeless-and-classics-zero)
– **可选**：[精妙背包](https://www.curseforge.com/minecraft/mc-mods/sophisticated-backpacks)
– **Minecraft 版本**：1.20.1
– **模组加载器**：Forge

## 📢 项目状态与社区驱动更新
AmmoToBox 的核心功能现已全部完成。本模组已进入**社区驱动模式**。 
后续更新将主要集中在修复问题和响应兼容性需求上。如果你希望支持你喜欢的背包模组，请在下方留言！你们的反馈将决定本模组的未来。

## 📢 社区共创福利！
AmmoToBox 设有**“首位提议者冠名权”**机制。如果你提议了新功能或模组兼容性，而我最终实现了它：
👉 **最先提出该建议的玩家，名字将永久刻在对应的界面按钮上！**（游戏中按 `V` 键查看界面。）

**如何认领你的位置：**
请在下方留言，并使用以下格式：
> `”建议兼容 [模组名]，我的游戏ID是：[你的ID]”`

*示例：“建议兼容 Travelers’ Backpacks，我的游戏ID是：Steve123”*
先到先得！快在下方留下你的点子！👇

******************************

# 弹药打包机 (AmmoToBox)
**厌倦了手动把几百发零散子弹一发发塞进弹药箱？让弹药打包机来帮你！**

这是一个为 [永恒枪械工坊：零 (TaCZ)](https://www.curseforge.com/minecraft/mc-mods/timeless-and-classics-zero) 量身定制的轻量级实用模组。它可以让你一键将背包里的散装子弹打包进弹药箱，并在材料充足时自动为你现场合成子弹并装箱。

## ✨ 核心特性
* **⚡ 一键打包**：自动扫描主背包、**潜影盒内部**，以及**精妙背包**，瞬间提取所有同型号的散装弹药。
* **⚙️ 智能自动合成**：自动读取 TaCZ 枪械工作台配方。材料足够时，自动扣除材料并合成弹药直接装箱，完美支持物品标签。
* **🖥️ 交互式设置面板**：按下 **`V`** 键即可呼出可视化 UI。玩家可直观地开关自动合成，并自由选择排除不想被检索的容器（如潜影盒、精妙背包），防止误用珍贵材料。（*注：若未安装精妙背包，面板会自动隐藏其对应按钮*）。
* **🛡️ 快照校验，绝对安全**：采用“快照-校验-扣除”的严格事务机制与 long 防溢出保护，彻底杜绝刷物品/吞物品的 Bug。扣除顺序已采用安全的硬编码逻辑，无需担心配置出错。
* **🔧 极速热重载**：服主修改 `.toml` 配置文件并保存后，设置即刻生效，**无需重启服务器**！（若部分独立服务器未即时刷新，只需输入一次 `/reload` 即可）。

## 🎮 如何使用
1. **确定型号**：先手动往弹药箱里装入至少一发子弹。
2. **一键装填**：手持弹药箱，**潜行 (Shift) + 右键**。
3. **玩家设置**：按 **`V`** 键呼出面板，可直观管理自动合成状态与容器检索白名单。

## 🔧 服主配置说明
配置文件位于 `serverconfig/ammotobox-server.toml`：
– `enableAutoCraft`：全局启用/禁用自动合成。
– `autoCraftDefault`：新玩家的默认自动合成状态。
– `maxCraftsPerOperation`：单次打包允许的最大合成批次。
– `ammoBoxMaxCount`：单个弹药箱的最大容量。
– `compatShulkerBox`：是否允许从潜影盒中提取弹药/材料。
– `compatSophisticatedBackpacks`：是否允许从精妙背包中提取。*（即使未安装精妙背包，开启此项也完全安全，不会报错）*。

## 📌 前置依赖
– **必须安装**：[永恒枪械工坊：零 (TaCZ)](https://www.curseforge.com/minecraft/mc-mods/timeless-and-classics-zero)
– **可选依赖**：[精妙背包 (Sophisticated Backpacks)](https://www.curseforge.com/minecraft/mc-mods/sophisticated-backpacks)
– **游戏版本**：1.20.1
– **加载器**：Forge

## 📢 模组状态与后续更新
弹药打包机的核心功能已全部开发完毕。本模组现正式进入**“社区驱动模式”**。
后续更新将主要以修复 Bug 和响应玩家需求为主。如果您希望兼容某款特定的背包模组，或者有绝佳的改进建议，请在评论区留言！你们的反馈将决定本模组未来的走向。

—

## 📢 社区共创福利（首发冠名制）
想要你的名字永久出现在模组的游戏内 UI 界面里吗？现在机会来了！
本模组开启了**“首发冠名制”**。如果你提出新功能或兼容建议且被我采纳：
👉 **第一个提出该建议的玩家，名字将被永久刻在对应的 UI 按钮上！**（游戏内按 V 键即可查看）。

**如何认领你的专属位置：**
请在下方评论区严格按照以下格式留言：
> `建议兼容 [模组名]，我的游戏ID是：[你的ID]`

*名额有限，先到先得！快在下面留下你的点子，让我们一起把这个模组做得更好！👇*