Magic Shulker Boxes

简体中文 | English

适用于 Minecraft Java 1.21.11 / Fabric / Java 21 的潜影盒自动收纳模组。

拾取自动入盒默认关闭。 单人房主可在“当前世界设置”开启；多人服管理员可在统一配置中设置 pickupStorageEnabled=true 后执行 /msb admin reload，也可开放个人设置让玩家自行开启。自动取料使用独立开关。

开启拾取自动入盒后，先让原版完成入包、来源扣减和回调，再整理真实收到的物品。同类专用盒优先；本次实际接收的同类物品加上受管杂物盒中的存量达到三组时，尝试完整归集到专用盒。未达到门槛且无同类盒的少量物品默认留在背包；开启 preferEmptyBoxesOverInventory 后，才优先使用受管杂物盒或从空盒分配新盒。真实地面余量和腾栏也可使用受管杂物盒。

盒内收纳依次尝试同类专用盒、模组受管杂物盒、可用空盒。同一类优先填装载程度较高的盒子；实际合并比较完整组件，不能合并不同名称、附魔或药水内容的堆叠。

0.13.0：默认保护全部快捷栏

快捷栏第 1–9 格默认全部保护：自动腾栏不会移走这些格子的物品，自动拆盒也不会把新盒放到这些格子。useHotbarForSpace 仍默认关闭；即使开启，也需要在“保护快捷栏”分组逐格关闭要使用的格子。

升级到 0.13.0 时，已有的服务端配置、玩家个人设置和单人客户端配置会自动迁移为九格全部保护：服务端配置补齐九项，个人稀疏覆盖把显式关闭改为开启，未设置的格子继续继承服务器默认值。原始文件先完整备份；没有更早迁移备份时使用 .pre-0.13.0.bak。迁移只执行一次，之后仍可逐格关闭。客户端和服务端应同时更新到 0.13.0。

每次取料数量

在 Mod Menu → 魔法潜影盒 → 个人设置中调整“每次取料数量”，或使用 /msb set refillAmount 23。可选 1–64 的整数；个人滑块最左端的“跟随服务器”会移除个人值，也可用 /msb reset refillAmount。房主在世界设置中修改默认值，管理员使用 /msb admin set refillAmount 23；是否允许个人修改仍由服务器控制。

例如设为 32：石头最多取 32 块，末影珍珠最多取 16 颗，工具取 1 件；来源只剩 7 件时取 7 件。数量也遵守物品组件定义的堆叠上限。每次只从一个来源栏位取料，不跨栏凑数。合成按配方取料，GCA 独立管理的补货不受此项控制。

从 0.11.0 升级时，原“每次取一组”开启迁为 64、关闭迁为 1，并同步迁移逐项权限。原文件保存在同目录的 .pre-0.12.0.bak；其他有效设置保留。客户端和服务器应同时更新到 0.12.0，旧设置通道不再接收。

0.11.0：自动受管杂物盒与三组分离

已有内容的盒子不会根据内容成为杂物盒。模组需要安置零散物品时，从玩家允许使用的真实空盒分配一个单盒并标记；堆叠空盒先安全拆出一个，剩余空盒没有标记。无需 F9 或玩家手动指定，角色跟随实际盒子而非固定格子。受管盒即使暂时只有一种物品或被取空，也保留角色。

三组门槛按每种物品的堆叠上限计算：

堆叠上限	创建专用盒的累计数量
64	192 个
16	48 个
不可堆叠	3 件

统计本次准备收纳的真实数量与受管杂物盒中的同类存量，不搬动无关原有盒的内容。达到门槛时，将受管杂物盒里的同类物品一起归集；纯单类受管盒可原地提升，混合盒中的其他物品保持原样。已有可用专用盒也会接收受管盒里的同类碎片。完整归集放不下时不做半次迁移，原有内容与角色保持；仍可在合法杂物盒中进行普通收纳。

标记只在玩家主背包与快捷栏内有效。直接换位、热键交换及自己的背包界面内临时光标整理保留；拿到外部容器界面的光标、移入箱子或末影箱、移到副手/装备、移出物品栏、丢出、死亡掉落或放置为方块都会取消。回来时作为普通盒处理，不自动恢复角色；只有以后再次从空盒分配时才会获得新角色。清理只删除本模组标记，保留名称、颜色、其他模组数据和全部内部物品。

快捷栏默认不腾栏，且第 1–9 格默认全部保护。若打开 useHotbarForSpace，还需在“保护快捷栏”分组关闭要使用的格子（将 protectHotbarSlot1 至 protectHotbarSlot9 对应项设为关闭）；受保护格不被自动腾栏，也不用于自动拆盒的空位。保护可以提前配置，不会启用快捷栏腾栏；各格沿用“继承／开启／关闭”、服务端逐项许可和普通设置快捷键。

例如允许第 1、9 格参与腾栏：

/msb set useHotbarForSpace true
/msb set protectHotbarSlot1 false
/msb set protectHotbarSlot9 false

上述命令须由服务端允许。旧 world/data/magic_shulker_boxes/junk-slots/ 文件保留但不再读取，不转换已有内容盒；旧 F9 手动格子功能已移除。当前个人设置和界面协议为 v9，两端使用设置界面时需升级到 0.13.0。

0.6.0：点击命令预览与快捷键

/msb show [选项] 显示自己的设置，/msb admin show [选项] 显示服务器设置，/msb admin player <玩家名|UUID> show 显示指定玩家的个人设置。列表为每个布尔值、模式值、继承/默认值及逐项权限提供可点击按钮：悬停预览完整命令，点击填入聊天框，按回车后才修改。聊天按钮只需安装服务端模组。

客户端 0.9.0 在“选项 → 控制 → 按键绑定 → 魔法潜影盒：个人设置切换”中，为全部个人布尔选项提供独立快捷键。默认均未绑定，玩家可以自行选择键盘或鼠标按键；绑定保存在客户端原版 options.txt，不发送到服务器。快捷键在游戏中切换当前有效值，保存和确认沿用个人设置协议；服务器只校验设置值是否获授权，不能选择或限制玩家绑定的键。锁定项会提示原因；保存待确认、恢复中或不支持协议时不会覆盖设置。

craftRefill 在 0.6.0 曾默认关闭，0.6.1 起恢复默认开启。新配置或未写此字段的配置使用 true，已有显式 false 保持关闭。管理员可执行 /msb admin set craftRefill true 开启现有服务器的合成补货；玩家获授权后也可用聊天按钮或自己绑定的快捷键切换。

0.5.0：容器、交易与末影箱

自动收纳现在覆盖地面拾取、容器向背包转移和村民交易产物。旧 configVersion: 2 文件保留；新增 enderChestRefill 默认关闭，省略 playerEditableSettings 时沿用开放全部个人选项的旧规则。GUI、原理图和 IPN 使用新版协议，两端都需要更新到 0.5.0；纯服务端容器与交易收纳仍无需客户端模组。

从容器与交易入盒

开启 pickupStorageEnabled 后，容器（包括普通箱子与末影箱）向背包 Shift 转移先完整执行原版行为，包括来源扣减、取物权限与回调，再按盒型、组件与拆盒设置整理实际入包的新增数量。默认只进入同类盒；preferEmptyBoxesOverInventory=true 时也可使用空盒。背包满导致原版未接收的物品保留在原槽，即使随身盒还有容量，也不提前抽取或根据旧快照补发。

只有能确认独立所有权的容器参与此收纳：真实世界方块容器、由独立容器组成的大箱子、本人末影箱，以及真实商人实体的交易容器。无法确认所有权的菜单可能正在编辑随身物品；打开期间保留原版转移，并暂停 MSB 对随身盒子的收纳写入，避免把取出的物品又放回来源盒或与另一写入方相互覆盖。该保护按容器所有权判断，不依赖模组名称。

普通取物和普通交易先放到鼠标光标；物品从光标放进背包后，优先入盒模式才收纳新增数量。拖动分配和容器热键换入背包也支持这一行为。背包内部整理及切换交易时自动退回的费用不触发收纳。合成菜单、命令发物品与丢弃不接入此收纳路径。

Shift 连续交易的产物、扣费、交易次数和经验全部先由原版处理，MSB 只整理已收到的新增物品。菜单后处理只使用已有空栏安全拆盒，不腾走旧物品，也不丢物品。数量未增加的背包内部整理不会被误认为新入包。

末影箱来源

开启 enderChestRefill=true 后，原理图取料、合成补货与 IPN 可读取本人末影箱的直接物品和其中潜影盒内部一层物品，无需放置或打开末影箱。各功能仍需各自开关开启。来源优先级为普通背包物品（由原版/IPN 查找）、随身潜影盒、末影箱直接物品、末影箱潜影盒；同一区域的盒子继续按较空优先。

服务器读取当前连接玩家的真实末影箱，客户端只接收本人的只读投影，最多约每半秒刷新一次。末影箱直接物品需要背包可用容量；盒内取料可按原有规则把被腾栏物品存回来源盒。末影箱堆叠盒在末影箱空栏拆分，随身堆叠盒在背包空栏拆分；失败保持来源不变。不读取别人存储或更深的嵌套容器，也不把末影箱外层潜影盒当作直接取出的物品。

工具回到来源原格

IPN 从盒中选择备用工具时，服务器在同一次事务中装备备用工具，将仍存在的旧工具放入同类盒或受管杂物盒；来源盒取出备用工具后为空或仍与旧工具同类时，优先复用备用工具的原格，保留耐久、名称、附魔及全部组件。普通背包候选仍优先；工具已经损坏消失时该格留空。来源或目标变化、锁定来源、拆盒空间不足及重复请求均拒绝；不需要临时背包工具栏。该行为同样适用于末影箱来源盒。消耗品仍通过 IPN 原有换手流程，空瓶仍保留在背包。

升级到 0.4.0：IPN 与合成补货

0.4.0 新增 ipnRefill=true 和 craftRefill=true，分别控制 IPN 潜影盒来源扩展与合成补货，独立于 pickupStorageEnabled、schematicRefill。允许个人设置时，四项服务端值都可作为默认值被玩家覆盖；关闭个人设置则统一使用服务端值。

0.3.2 的 configVersion: 2 文件与已有选择保留，不重置；省略新开关时按默认开启处理。使用新图形设置和 IPN 补货时两端都更新到 0.4.0。合成取料可由服务器执行，0.4.0 客户端额外提供盒内材料的配方书可合成统计。较早版本继续按下述既有规则备份迁移。

升级到 0.3.2：个人开关与配置键改名

服务端允许个人设置（allowPlayerSettings=true）时，pickupStorageEnabled 和 schematicRefill 是服务端默认值，玩家可分别覆盖为开或关。关闭个人设置时，所有玩家统一使用服务端值。原 enabled 键已改名为 pickupStorageEnabled；新配置、命令和网络设置只接受新名称。

0.3.1 的 configVersion: 1 配置会在首次读取时完整备份到同目录的 <原文件名>.pre-0.3.2.bak，随后一次性改写为 configVersion: 2，保留原开关值及其余选项。服务端总配置、服务端保存的在线和离线玩家偏好、客户端偏好均会迁移。备份失败、已有同名但内容不同的备份或无效字段会保留原文件并报错。新版本的个人设置和取料通道已更新；使用这两项功能时客户端与服务端都需升级到 0.3.2。纯服务端入盒仍无需客户端安装。

升级到 0.3.1：备份并重置旧配置

0.3.0-alpha 及更早版本的配置没有版本标记。首次读取时，0.3.1 会把原文件完整备份为同目录的 <原文件名>.pre-0.3.1.bak，再全部重置；包括 config/magic_shulker_boxes.json、客户端 config/magic_shulker_boxes-client.json 和存档下 data/magic_shulker_boxes/players/<UUID>.json。服务端启动会处理已有玩家文件，包括离线玩家。客户端启动会处理本地偏好。

0.3.1 的统一配置恢复默认值：旧键 enabled=false、allowPlayerSettings=false；个人覆盖项清空，重新继承服务端。自动取料仍由 schematicRefill 独立控制，默认 true。该版本生成 configVersion: 1 文件；0.3.2 会按上节迁移为版本 2。请保留版本标记；备份不自动恢复，也不参与运行。需要恢复某些选择时，将所需选项填写到新文件并保留其版本标记。

备份失败或已存在内容不同的备份时，保留原文件并记录错误，不覆盖备份。损坏 JSON、未知配置版本和新版非法字段也会保留并报错。使用 0.3.2 的个人设置时两端都需更新；旧客户端不能把旧偏好重新上传。只用服务端收纳的玩家仍无需安装客户端模组。

安装

• 多人服务器：在 Fabric 1.21.11 服务端 的 mods 中安装本模组及对应版本的 Fabric API。玩家客户端无需安装本模组。
• 单人 / 局域网房主：在客户端实例的 mods 中安装同样的两个模组，由内置服务端执行收纳。
• 客户端单独安装不能让未安装本模组的远程服务器自动收纳。
• 使用 Fabric Loader 0.18.4 或更新版本。项目开发和测试使用 0.19.5、Fabric API 0.141.6+1.21.11。

构建产物在 build/libs。安装普通 .jar，不要安装 -sources.jar。

图形设置（Mod Menu + YACL）

客户端可额外安装 Mod Menu 17.0.1 和 YACL 3.8.2（Fabric 1.21.11）。它们是可选依赖，独立服务端无需安装。升级时移走旧版本本模组 JAR，避免重复加载。

入口：模组 → Magic Shulker Boxes → 配置。界面跟随游戏语言，支持简体中文和英文；每个选项都有说明。

• 个人设置：布尔选项选择“跟随服务器 / 开启 / 关闭”，腾栏方式也有“继承”选项。重置为“继承”会删除该个人覆盖项；取消或不保存退出不写入文件。
• 主菜单：修改本地个人设置，稍后加入允许个人设置的服务器时同步。
• 游戏内：服务端需安装支持图形设置及恢复查询协议的本模组版本，且开启 allowPlayerSettings 才能从界面修改个人设置。保存等待服务器确认，成功后写回本地文件；服务器拒绝、频率限制和超时均有提示。关闭个人设置时锁定编辑。
• 当前世界设置 / 世界默认设置：仅主菜单与单人 / 局域网房主可见，顶部直接切换，修改此实例的统一设置，包括独立的入盒、取料开关和“开放个人设置”。保存后立即生效；加入远程服务器的玩家看不到此页。

两页独立保存；切换时若有未保存草稿，会提示丢弃或返回编辑。服务端策略或连接发生变化时，已打开的个人设置页需要重新打开，避免提交过期草稿。左侧名称为固定标签，右侧按钮切换开关和模式（右键反向切换），数量滑块支持鼠标和方向键逐个调整，旁边的重置按钮恢复该项默认值。个人设置可选择继承，世界设置直接选择实际值。选择“跟随服务器”时，选项行直接显示收到的值，例如“跟随服务器（开启）”；未连接或未收到该值时显示“未同步”，不会猜测默认值。服务端同步更新后显示随之刷新，旧草稿仍需重新打开。说明中也显示服务端默认值；服务端默认关闭入盒或取料时分别提示。只安装 Mod Menu 而未安装 YACL 时，配置入口会显示缺少依赖的提示。

“拾取时自动入盒”（pickupStorageEnabled）与“Litematica 自动取料”（schematicRefill）独立：可以只入盒、只取料、两者开启或两者关闭。pickupStorageEnabled=false 只关闭拾取入盒。若关闭个人设置并统一关闭两项功能，请同时设置 schematicRefill=false。

保存超过 10 秒未确认时，会暂停继续保存并查询服务端已保存的设置；迟到确认仍可处理。若本地文件写入失败，当前游戏和设置页仍使用服务端确认的值，并明确提示本地保存失败。未完成的保存会留下按服务器和玩家隔离的恢复标记；重连或重启客户端后先查询服务端，再恢复编辑，不会直接上传旧本地文件。同步完成后重新打开设置页。

原理图自动取料

客户端安装 Litematica 0.26.16 / MaLiLib 0.27.20（Minecraft 1.21.11），客户端与服务端都安装 Magic Shulker Boxes 0.13.0，保持版本一致。新版不再接受旧取料协议，个人设置需使用兼容的同步协议。单人游戏只需在客户端实例安装；专用服务端不需要 Litematica 或 MaLiLib。

启用 Litematica 轻松放置，对准原理图并使用它的放置键。背包及副手已有材料时沿用原有行为；缺料时从潜影盒取出匹配材料，等服务端同步背包后继续放置。持续按住放置键即可继续；单次点击可能只完成取料，此时再点一次。支持旧版及重写版轻松放置。普通选取方块、创造模式、箱子界面及鼠标光标持物时不自动取料。

背包满时，默认把物品直接收进同类盒或受管杂物盒腾栏，全程不丢物品。来源盒只有在取料后为空或仍与被移动物品同类时才可接收。快捷栏九格默认全部保护，并沿用 useHotbarForSpace、allowPartialStacksForSpace 设置。不会把潜影盒搬入另一个盒子。数量大于 1 的来源盒需要额外空栏拆出一个；没有安全空间时不修改物品。Carpet 通常只允许空盒堆叠，空盒中没有可取的材料。

取料优先选择未满盒，多个未满盒中先取装载程度较低的，尽量先用空一个盒子。满盒作为后备；无法安全取料的来源会被跳过。客户端查找和服务端实际取料都使用这一顺序，装载程度相同时按背包栏位顺序。

菜单新增“原理图取料”分组：

设置	默认	行为
schematicRefill	true	独立控制自动取料；允许个人设置时，玩家可覆盖服务端默认值
refillAmount	64	每次投影取料或 IPN 补货取 1–64 件，不超过来源剩余数量和物品自身堆叠上限
refillMakeSpace	true	满背包时直接收纳腾栏，与拾取时的丢出模式独立
refillFailureMessages	true	控制非空间原因的补货失败提示；空间不足由独立开关控制，成功不提示
spaceFailureMessages	true	独立控制收纳、取料、工具替换与合成腾栏的空间不足提示；每 40 tick 限频，关闭不改变物品行为

失败提示区分缺少匹配材料、空间不足、功能禁用和服务器不支持。空间不足默认显示，可通过独立 spaceFailureMessages 关闭在快捷栏上方，所有收纳和腾栏入口共用每 40 tick（正常 TPS 下两秒）一次的限频；不会把材料缺失或过期请求误报为空间不足。refillFailureMessages=false 只关闭其他补货失败提示，不影响取料行为。个人设置是否可修改仍由 allowPlayerSettings 控制。关闭拾取入盒后，取料仍可按 refillMakeSpace 将背包物品移入同类盒或受管杂物盒腾栏。

客户端查找材料时比较完整物品组件，包括自定义名称；请求还携带组件指纹，服务端发现来源已变化时会拒绝取料。无法可靠编码的临时组件同样拒绝。两端都需支持新的取料协议，旧协议不会绕过校验。先搜索普通背包及可选副手盒；开启 enderChestRefill 时再读取本人末影箱，不读取更深的嵌套容器。客户端仅在缺料尝试时查询，每半秒最多请求一次；服务端核对真实盒内物品、游戏模式和界面状态。客户端不提供权威物品数据，也不预先修改背包。

IPN 消耗品与工具补货

0.4.0 起支持此功能。客户端安装 Inventory Profiles Next 2.2.6（Fabric 1.21.11） 及它要求的 libIPN、Fabric Language Kotlin；客户端与服务端都安装 Magic Shulker Boxes 0.10.1，保持版本一致。服务端无需 IPN，单人实例同时提供两端。

启用 IPN 原有自动补货后，主手或副手的消耗品补货、工具替换先查找背包候选。没有可用物品时，本模组将背包潜影盒内物品交给 IPN 原有的筛选和排序方法。是否触发、等待时间、药水效果、食物替代、名称/组件匹配、工具类别、耐久阈值、自定义排序和禁用补货栏位均由 IPN 决定。本模组不另设这些规则，也不接入盔甲补货。

ipnRefill=true 默认允许这一来源扩展，与 pickupStorageEnabled、schematicRefill 独立。允许个人设置时可使用 /msb set ipnRefill true 覆盖服务端默认值。配置菜单有独立的 Inventory Profiles Next 分组。

随身来源使用 IPN 的背包储物栏（索引 9–35），遵守锁定栏位；快捷栏和副手盒子不作为 IPN 来源。开启 enderChestRefill 后，额外读取本人末影箱。消耗品取到 IPN 可见背包栏后继续原换手流程；盒中工具按 0.5.0 的原格回存事务替换。

取物沿用 refillMakeSpace、splitStackedBoxes、allowPartialStacksForSpace 和 matchItemComponents 的同类收纳腾栏保护；IPN 排除的锁定栏位也不会用于取物或拆盒。若 IPN 设置允许使用锁定栏位，本模组遵循这一选择。IPN 每次候选堆叠按 refillAmount 取料；不可堆叠物品最多 1 件，堆叠上限为 16 的物品最多 16 件。工具替换始终为 1 件。无法安全取出时物品保持不变，IPN 沿用自身失败处理。服务器不支持这一协议时，IPN 继续原有背包补货。

合成材料补货

0.4.0 起支持背包 2×2 和工作台 3×3 合成补货。不依赖 IPN。服务端安装 0.4.0 即可执行取料；0.4.0 客户端还能让配方书根据盒内材料显示可合成状态，并在盒内数量变化后刷新。

设置中的“合成补货”分组提供“从潜影盒补充合成材料”（craftRefill），默认 true，独立于自动入盒、原理图取料和 IPN 补货。允许个人设置时，可用 /msb set craftRefill false 关闭或 /msb set craftRefill true 开启。

• 点击配方：沿用原版配方填充、材料匹配及配方权限，从背包材料不足的部分继续取用潜影盒内容。Shift 点击配方的数量由原版批量规则决定。材料直接进入合成格，满背包时不需要额外材料栏；旧合成格物品必须能安全放回背包。
• 取出成品：普通点击和 Shift 连续合成都可补货。按服务端观察到的输入排列，为耗空的格子补回一个相同类型、相同组件的物品；仍有材料的格子保持原数量。先用普通背包，再从潜影盒取。整套缺失材料不足或余留物无法安全保存时，停止补货，不部分取出。

原版先处理合成余留物。补回被桶、瓶等余留物占据的耗空格子时，余留物优先放到普通背包；背包满时，可按 refillMakeSpace、allowPartialStacksForSpace 和 matchItemComponents 保存到同类盒或受管杂物盒；来源盒取料后为空时也可复用。成品仍由原版点击或 Shift 操作放到鼠标或背包。

来源为普通背包、快捷栏中的潜影盒，以及 includeOffhand=true 时的副手盒。来源盒按装载程度较低优先搜索；堆叠盒沿用 splitStackedBoxes，需独立空栏拆出一个。开启 enderChestRefill 时也可从本人末影箱取料；不读取更深的嵌套容器，不用于熔炉、炼药台、切石机等其他菜单。创造/旁观模式不自动取料。配方书沿用原版对命名、损伤和附魔物品的自动填充限制；手动配方的连续补货则严格保持原输入组件。

配方填充在副本上规划来源变化，组件冲突、拆盒空间冲突或不能完整填充时回退。一个潜影盒不能同时提供内部材料并成为同一配方的原料。

Carpet 假人：使用 GCA

从 0.8.0 开始，MSB 不再为 Carpet 假人补充手持物品或替换损坏工具。此行为统一使用 Gugle Carpet Addition（GCA）。服务端安装 Carpet 与 GCA 后，开启并持久保存以下两项补货规则：

/carpet setDefault fakePlayerAutoReplenishment true
/carpet setDefault fakePlayerAutoReplenishmentFormShulkerBox true

第二项才启用潜影盒来源；仅开启第一项只从普通背包补货。来源顺序、补货数量、拆盒与失败处理由 GCA 控制，MSB 的 refillAmount、includeOffhand 和腾栏选项不控制 GCA。GCA 工具替换另有独立规则。MSB 继续保留 Carpet 堆叠盒兼容，以及普通玩家的 IPN、原理图和合成补货。

已有版本 2 的服务端、客户端和 UUID 偏好文件若含 carpetRefill 或 playerEditableSettings 中的同名许可，仅涉及该旧项时会先逐字节备份为 .pre-0.8.0.bak；同时涉及单类收纳迁移时使用 .pre-single-type.bak，再只删除这些旧项；其余设置和字段许可保持原值。无效文件或冲突备份不覆盖。磁盘配置仍为版本 2；设置/GUI 协议使用 v9，需客户端与服务端同时升级。

Carpet 堆叠兼容

可以与 Carpet 的 stackableShulkerBoxes 规则一起使用；本模组不会替你开启该规则，也不要求安装 Carpet。

数量大于 1 的潜影盒必须先拆出 一个，放到独立主背包或快捷栏栏位，才会修改其内容。默认先寻找现有可用盒子；仍有物品装不下且没有空栏时，会自动腾出一栏。不会借用装备栏、副手或鼠标光标，也不会搬走潜影盒来腾位置。

默认先使用已有可用同类盒，再放背包；没有同类盒且背包有空间时不新建盒。若希望无同类盒时也优先进盒，将 preferEmptyBoxesOverInventory 设为 true；此时背包未满也会先使用空盒，有空栏即可拆分堆叠盒。

自动腾栏

makeSpaceMode 有三种行为：

• MOVE_TO_BOX（默认）：把选中栏位的物品直接移入同类盒或受管杂物盒，再为拾取物拆盒，全程不落地。
• DROP_AND_PICKUP：在玩家脚下生成选中栏位的掉落物，为每个实际被移动的堆叠预留合法同类盒或受管杂物盒，再立即通过游戏拾取流程收回。全部掉落实体生成成功后才提交腾栏；任一生成失败就不腾栏；若其他模组阻止回收，剩余物品保留在地面，带有禁止再次触发腾栏的标记。
• DISABLED：不主动腾栏，没有空栏就跳过堆叠盒，继续尝试其他盒子。

不要求物品满一组：3 个石头也可以腾栏，需将该栏的 3 个都移走才能空出栏位。新盒自身占格也计入规划，不能把一栏物品换成新盒就误报释放空间。默认只选择背包主区域，优先与拾取物同类，再考虑其他可入盒物品；可以另行允许使用快捷栏。移动前在背包副本上确认全部被移动物品都能放下，并且仍能接收至少一个本次拾取物，否则不动背包。需要两个新盒却没有空栏时，可将两栏同类物品合并到一个新盒，再把另一栏用于拾取物的盒子。

被腾走的小量石头、圆石和砂砾可以进入同一个模组创建的受管杂物盒；同类数量达到三组后完整分离到专用盒。拾取、容器转移、原理图/IPN 取料腾栏、工具替换、合成余留物和丢出后的即时回收遵守同一分类规则。原有混合内容盒仍可取料，但不会被改为杂物盒或接收无关新类型。

同类要求物品 ID 与以下关键内容一致，即使 matchItemComponents=false 也会比较：

• 药水、喷溅/滞留药水及药水箭：完整药水内容（基础类型、自定义效果、颜色等）和药效时长倍率。普通、延长及增强版分别分类。
• 可疑炖菜：效果和持续时间。
• 附魔书：存储的附魔种类和等级。
• 已填写地图：地图编号。
• 烟花火箭、烟火之星：飞行时长和爆炸内容（形状、颜色、轨迹等）。
• 山羊角：乐器/声音。
• 不祥之瓶：等级。

“严格比较全部组件”默认关闭，额外决定是否比较自定义名称、普通装备的附魔/耐久等其他差异。专用匹配与自动分离时，不同效果的药水分别累计；受管杂物盒可暂存不同效果，但不能把它们算成同类或合并。同种药水只是经铁砧改名时，关闭该项可同盒，开启后分盒。其他未列入关键内容的组件仍由此开关控制；同盒中的不同组件堆叠始终分别保留。

支持原版所有颜色的潜影盒，保留盒子名称、颜色、其他组件和内部物品数据；不允许嵌套潜影盒。

配置

首次启动会在执行收纳的一侧生成 config/magic_shulker_boxes.json。多人服修改服务端文件；单人世界修改客户端实例文件。修改后使用管理员命令 /msb admin reload，或重启服务端/客户端。

完整配置示例与默认值一致。

配置项	默认	含义
enderChestRefill	false	启用本人末影箱直接物品与潜影盒取料来源
playerEditableSettings	全部设置名	总开关开启时可由玩家修改的字段列表，[] 全部锁定
allowPlayerSettings	false	仅服务端策略：是否允许玩家个人设置；关闭时所有玩家统一使用本文件
pickupStorageEnabled	false	默认关闭；仅控制拾取时自动入盒，与自动取料独立；允许个人设置时，玩家可覆盖服务端默认值
preferEmptyBoxesOverInventory	false	同类盒始终优先；开启后无同类盒时也优先使用空盒，再放背包
useMatchingBoxes	true	使用同类专用盒
useEmptyBoxes	true	使用空盒
splitStackedBoxes	true	允许拆分堆叠盒，包括自动腾栏；关闭时整组跳过
makeSpaceMode	"MOVE_TO_BOX"	无空栏时直接收纳腾栏；可选 "DROP_AND_PICKUP" 或 "DISABLED"
useHotbarForSpace	false	是否允许从快捷栏搬走物品腾栏；默认仅背包主区域
protectHotbarSlot1 至 protectHotbarSlot9	true	逐格保护快捷栏，不腾走该格，也不用于自动拆盒；关闭后该格可用于腾栏和拆盒目的地；不会启用快捷栏腾栏
allowPartialStacksForSpace	true	是否允许未达到物品最大堆叠数的零散物品用于腾栏，两种腾栏方式都遵守
preferExistingBoxesBeforeMakingSpace	true	先使用所有现有可用盒子，再尝试腾栏；false 时按原类别顺序遇到堆叠盒就尝试腾栏
includeOffhand	false	是否查找副手里的潜影盒；拆分目的地仍限主背包与快捷栏
matchItemComponents	false	始终比较物品 ID 与上述关键内容；true 还要求名称、普通装备附魔/耐久等全部组件一致
ipnRefill	true	允许 IPN 从背包潜影盒补货，匹配和触发规则由 IPN 决定
craftRefill	true	允许从随身潜影盒补充合成材料

“一种物品”按种类而不是占用栏数计算：装有多组圆石的盒子仍是单类盒。无论如何设置种类判断，真正合并内部物品堆叠时都会严格比较组件，不会把不同附魔、名称或药水效果合并。物品各自的最大堆叠数仍然生效。

playerEditableSettings 使用设置名数组，makeSpaceMode 使用上表中的字符串，其余配置项只接受 JSON 布尔值 true / false，可以省略字段以使用默认值。无效 JSON、未知字段、未知模式或错误类型会记录错误并同时禁用自动入盒和自动取料，原文件保留，原版拾取仍可使用。

收纳适用范围及光标、交易容量规则见上方“从容器与交易入盒”；末影箱来源是独立取料开关。

玩家个人设置与语言

游戏内提示支持简体中文和英文，跟随玩家的 Minecraft 语言；未安装客户端模组的玩家也能看到服务端提供的对应语言回退。其他语言回退为英文。命令、JSON 字段和模式值使用固定英文名称，两种语言通用。模组显示名统一为 Magic Shulker Boxes，简介提供中英文。

服务端默认 allowPlayerSettings=false，忽略个人配置。管理员可以实时切换并保存：

/msb admin player-settings true
/msb admin player-settings false
/msb admin reload
/msb admin show
/msb admin show craftRefill
/msb admin set craftRefill false
/msb admin reset craftRefill
/msb admin permission craftRefill true
/msb admin permissions all
/msb admin permissions none

上述管理命令要求 Minecraft 的 COMMANDS_ADMIN 权限（通常为 OP 等级 3），服务端控制台也可执行。allowPlayerSettings=false 时，服务端的入盒和各类补货开关对所有玩家生效；设为 true 后，仅获 playerEditableSettings 授权的服务端值成为可覆盖的默认值；其余强制使用服务端值。重载失败时保留此前有效配置。

admin set 保存任意服务器设置，admin reset <选项> 只恢复该项代码默认值；不会重置其他设置。permission <选项> <true|false> 开放或锁定一项个人修改权限，permissions all|none 一次开放或锁定全部选项，总开关仍独立。playerEditableSettings 也可通过 admin set 写入 JSON 名称数组。无效值会被拒绝，写入失败保留此前有效配置。列表中的按钮只预览命令，回车提交后才保存并同步策略。

管理指定玩家的个人设置

管理员和服务端控制台可使用以下命令，权限要求与其他管理命令相同：

/msb admin player Steve show
/msb admin player Steve set pickupStorageEnabled true
/msb admin player Steve set makeSpaceMode MOVE_TO_BOX
/msb admin player Steve reset pickupStorageEnabled
/msb admin player Steve reset

Steve 可替换为在线玩家名、服务器能解析的离线玩家名或 UUID。名字无法解析时，使用 UUID 可直接管理该存档中的个人文件。每条命令只处理一个玩家；玩家名补全来自在线名单，选项和值也支持补全。/msb admin 显示管理命令帮助。

show 显示目标玩家的 UUID、每项已保存的个人值（未设置则显示“继承”）、当前生效值和授权状态。set 只改指定项，保留其他个人选择；reset <选项> 清除此项以恢复继承，reset 清除全部个人选择，包括暂时被锁定的项。选项和值与普通玩家命令一致，策略字段不能写入个人设置。

管理员可编辑或清除暂未获授权的个人值，服务器的总开关和逐项锁定仍决定实际生效值。保存时会提示该值已生效还是暂存待授权。读取或写入失败会报告错误，损坏文件保留供修复。对在线玩家的修改会立即更新服务端记录，并通过现有协议同步到已安装本模组的客户端；无需目标玩家重新登录。离线修改保存在服务器，客户端下次入服仍遵循下方的本地个人文件上传规则，因此可能覆盖离线期间的管理修改。

逐项授权

在服务器配置中设置 playerEditableSettings 为允许修改的设置名数组，再执行 /msb admin reload。例如只允许原理图与 IPN 的个人开关：

"allowPlayerSettings": true,
"playerEditableSettings": ["schematicRefill", "ipnRefill"]

省略数组表示全部开放（仍需总开关开启），[] 表示无可编辑项。所有 StorageConfig 选项都可列入，包括 enderChestRefill 和 makeSpaceMode；策略字段本身不能授权玩家修改。世界设置页提供逐项开关。个人 GUI 对未获授权项禁用控件并显示服务器值；命令、同步、GUI 保存与运行时配置均由服务端复核。管理员撤权后，已有个人文件的对应值立即不再生效，保留为未启用的选择；恢复授权后可以再次使用。非法或重复设置名拒绝加载，失败重载保留旧策略。

开放个人设置后，普通玩家无需安装客户端模组即可使用：

/msb
/msb show
/msb set pickupStorageEnabled false
/msb set schematicRefill true
/msb set makeSpaceMode MOVE_TO_BOX
/msb set allowPartialStacksForSpace true
/msb reset

show [选项] 显示当前实际生效的配置；获授权项可点击值和“继承”按钮预览完整命令。set 立即生效，支持所有 StorageConfig 选项；服务器策略字段仅限管理命令。reset <选项> 恢复单项继承，reset 清空当前允许修改的个人覆盖项。命令带选项和值的补全。每人只能修改自己的配置，关闭个人设置后 set/reset 会被拒绝。

个人设置按 UUID 保存在当前存档的 data/magic_shulker_boxes/players/<UUID>.json，重启后保留，不同存档互不影响。只保存玩家修改过的选项，其他选项始终继承服务端当前默认值。管理员手动修复这些文件后，可用 reload 清除缓存。

可选的客户端同步

客户端安装本模组后，首次生成 config/magic_shulker_boxes-client.json，初始内容为 {}，表示全部继承服务端默认。可参考个人设置示例。

加入支持本模组且允许个人设置的服务器时，客户端会自动提交此文件；服务器切换为允许或重载策略时也会重新同步。提交仅替换获授权选项，未获授权的既存选择保持保存但不生效。服务器关闭个人设置时不会上传，本地文件保留。修改本地文件后重新加入服务器即可同步。

通过 /msb set/reset 成功修改后，已安装模组的客户端会同步保存到本地个人文件，所以重新加入后仍保持一致。该本地文件由此客户端实例共用，会在其他允许个人设置的服务器上使用；纯服务端玩家只使用各存档中的服务器保存记录。同步只涉及收纳行为设置，不能更改服务端策略。

开发

见 构建、测试与代码结构。

旧磁盘配置中的三个混装选项及对应权限会在校验通过后移除；onlyWhenInventoryFull 按反值迁移为 preferEmptyBoxesOverInventory，对应权限同步改名。原文件完整备份为 .pre-single-type.bak，其他设置保留。命令与网络输入不再接受这些旧选项；请同时更新使用个人设置的客户端。无效文件或冲突备份不会被覆盖。