Описание
# Beyond Storage Addon
这是一个为 **[Beyond Dimensions](https://modrinth.com/mod/beyonddimensions)** 开发的附属模组：在普通容器界面提供按钮和快捷键，把物品一键存入维度网络。
## 功能概览
- **整理存入**：普通 `F` 默认只把目标网络里**已有同类**的物品存入网络。
- **全部存入**：`Ctrl+F` 与界面「全部存入」按钮，一键存入符合安全规则的全部物品。
- **目标网络**：可绑定指定维度网络，避免不知道物品进了哪个网络。
- **游戏内配置**：`/bs_addon` 系列命令，无需先改配置文件。
- **匹配模式**：同类匹配 / 精确匹配；潜在容器类物品更谨慎。
- **界面控制**：可按 Screen/Menu 类名前缀隐藏按钮、禁用快捷键或完全禁用一键存入；输入框聚焦时避免误触。
- **安全策略**：服务端校验容器、先模拟网络容量再抽取、跳过不安全槽位，降低复制/吞物品风险。
## 支持版本
与 Beyond Dimensions 的发布矩阵对齐：
| Minecraft | 加载器 | 文件 |
| --- | --- | --- |
| 1.20.1 | Forge | `BS_addon_forge-1.20.1-1.3.0.jar` |
| 1.21.1 | NeoForge | `BS_addon_neoforge-1.21.1-1.3.0.jar` |
| 1.21.11 | NeoForge | `BS_addon_neoforge-1.21.11-1.3.0.jar` |
| 26.1.2 | NeoForge | `BS_addon_neoforge-26.1.2-1.3.0.jar` |
| 26.2 | NeoForge | `BS_addon_neoforge-26.2.0-1.3.0.jar` |
> 1.21.11 需配合对应版本的 Beyond Dimensions（含 alpha）。请下载与你游戏版本、加载器一致的文件。
## 使用方法
### 安装
1. 安装 **Beyond Dimensions** 与本模组（**客户端与服务端都需要**）。
2. 启动游戏后，打开任意普通容器（箱子、熔炉、背包界面上的其他容器等）。
3. 使用下方按钮、快捷键或命令完成存入。
### 按钮与快捷键
| 操作 | 默认行为 | 说明 |
| --- | --- | --- |
| 界面「全部存入」按钮 | 全部存入 | 行为固定为全部存入；开关见 `showButton` / `/bs_addon button` |
| 普通 `F` | **整理存入** | 只把目标网络里**已有同类**的物品存入；可用 `/bs_addon mode normal` 改 |
| `Ctrl+F` | **全部存入** | 存入符合安全规则的全部物品；可用 `/bs_addon mode ctrl` 改 |
补充说明：
- 快捷键总开关：`/bs_addon hotkey on|off` 或配置 `enableHotkey`。
- 默认在搜索框/输入框聚焦时**不会**触发快捷键（`ignoreHotkeyWhenTyping=true`），避免在精妙存储等界面输入 `F` 时误存。
- 部分界面可通过配置隐藏按钮、禁用快捷键，或完全禁用一键存入（见下方配置）。
- 按钮开关需要**重新打开容器界面**后才会显示/隐藏；快捷键与目标网络等修改会立即生效。
- 服务端有请求冷却（默认 250ms），同一玩家在同一容器内高频连按会被限流。
### 整理存入 vs 全部存入
- **整理存入（smart）**：只转移「目标维度网络里已经存在」的物品。网络没有的物品会尝试放回玩家背包；背包满则留在原容器，**不会丢弃或复制**。
- **全部存入（all）**：在安全槽位策略允许的前提下，尽可能把容器内物品全部存入网络。
- **匹配模式**影响「网络是否已有」的判断（仅整理存入）：
- `same` 同类匹配（默认）：同物品 ID 即视为已有；不同附魔书、不同耐久工具等同 ID 物品也会按已有同类处理。潜在容器/存储类物品仍更严格。
- `exact` 精确匹配：物品 ID 与 NBT/组件都必须一致。
### 目标网络
- 默认 `targetNetworkId=-1`：跟随当前 Beyond Dimensions **主网络**。
- `/bs_addon target set `：绑定到指定网络 ID。
- `/bs_addon target clear`：清除绑定，恢复跟随主网络。
- `/bs_addon target status`：查看当前绑定状态。
### 游戏内命令一览（`/bs_addon`）
命令为**客户端配置命令**，会写入 `config/beyondstorage.properties`。
| 命令 | 作用 |
| --- | --- |
| `/bs_addon` 或 `/bs_addon help` | 显示帮助 |
| `/bs_addon status` | 显示按钮、快捷键、普通 F 模式、Ctrl+F 模式、匹配模式状态 |
| `/bs_addon button on` | 显示「全部存入」按钮（需重开容器界面） |
| `/bs_addon button off` | 隐藏按钮（需重开容器界面） |
| `/bs_addon hotkey on` | 启用快捷键 |
| `/bs_addon hotkey off` | 禁用快捷键 |
| `/bs_addon mode status` | 查看普通 F / Ctrl+F / 匹配模式 |
| `/bs_addon mode normal smart` | 普通 `F` = 整理存入 |
| `/bs_addon mode normal all` | 普通 `F` = 全部存入 |
| `/bs_addon mode ctrl smart` | `Ctrl+F` = 整理存入 |
| `/bs_addon mode ctrl all` | `Ctrl+F` = 全部存入 |
| `/bs_addon match same` | 整理存入使用同类匹配 |
| `/bs_addon match exact` | 整理存入使用精确匹配 |
| `/bs_addon target status` | 查看目标网络（绑定 ID 或主网络） |
| `/bs_addon target set ` | 绑定目标网络（`` 为 ≥0 的整数） |
| `/bs_addon target clear` | 清除目标网络绑定 |
| `/bs_addon debug current` | 输出**上次打开界面**的 Screen / Menu 完整类名（便于填配置前缀） |
| `/bs_addon debug last` | 输出**上次成功发起存入**时的 Screen / Menu 类名 |
`debug` 用法示例：打开某个模组的箱子界面 → 聊天栏执行 `/bs_addon debug current` → 把打印的类名（或包名前缀）填进配置的 `hideButtonInScreens` / `disableHotkeyInScreens` / `disableQuickStoreInContainers`。
## 配置
配置文件路径：
```text
config/beyondstorage.properties
```
首次启动若文件不存在会自动生成。部分选项可用 `/bs_addon` 命令直接改写；其余选项请编辑本文件后重启客户端/服务端（视选项而定；命令改写的项会立即保存）。
### 配置项一览
| 配置键 | 默认值 | 说明 |
| --- | --- | --- |
| `showButton` | `true` | 是否在支持的容器界面显示「全部存入」按钮。可用 `/bs_addon button on\|off`。改后需重开容器界面。 |
| `enableHotkey` | `true` | 是否启用快捷键。可用 `/bs_addon hotkey on\|off`。 |
| `targetNetworkId` | `-1` | 一键存入使用的网络 ID。`-1` = 跟随 BD 主网络。可用 `/bs_addon target set\|clear`。 |
| `normalStoreMode` | `smart` | 普通 `F` 的行为：`smart` = 整理存入，`all` = 全部存入。可用 `/bs_addon mode normal smart\|all`。 |
| `ctrlStoreMode` | `all` | `Ctrl+F` 的行为：`smart` / `all`。可用 `/bs_addon mode ctrl smart\|all`。 |
| `existingItemMatchMode` | `same` | 整理存入时如何判断「网络已有」：`same` 同类匹配，`exact` 精确匹配。可用 `/bs_addon match same\|exact`。 |
| `ignoreHotkeyWhenTyping` | `true` | 搜索框/文本框聚焦时忽略快捷键，防止输入 `F` 误触发。 |
| `hideButtonInScreens` | （空） | **隐藏按钮**的 Screen/Menu 类名前缀列表，逗号或分号分隔。示例：`net.p3pp3rf1y.sophisticatedstorage.` |
| `disableHotkeyInScreens` | （空） | **禁用快捷键**的 Screen/Menu 类名前缀列表。写法同上。 |
| `storePlayerInventory` | `false` | 打开容器时是否也从**玩家自己的背包槽位**存入网络。默认关闭，避免误清空背包。 |
| `requireSlotMayPlace` | `true` | 只移动「允许放回同类物品」的槽位。用于规避机器输出槽、虚拟槽等不安全槽位。建议保持开启。 |
| `requestCooldownMs` | `250` | 同一玩家在同一容器内一键存入请求的冷却（毫秒），范围 0–5000。高延迟服务器可适当加大。 |
| `disableQuickStoreInContainers` | `com.wintercogs.beyonddimensions.` | **完全禁用**一键存入的容器类名前缀（按钮、快捷键、服务端请求全部拦截）。默认屏蔽 Beyond Dimensions 自身界面。旧键名 `blockedContainerClassPrefixes` 仍可读。 |
类名前缀匹配规则：
- 对当前 Screen 或 Menu 的类名及其**父类**做前缀匹配。
- 多个前缀用英文逗号 `,` 或分号 `;` 分隔。
- 推荐用 `/bs_addon debug current` 查看完整类名，再截取稳定包前缀填写。
安全相关默认行为（无需配置即可生效）：
- 默认跳过玩家背包（除非 `storePlayerInventory=true`）、Beyond Dimensions 自身容器、不可拾取槽位，以及不安全的输出/虚拟槽位。
- 存入前先模拟网络容量，只抽取实际可存入数量；失败剩余回填原槽位。
- 整理存入时，网络没有的物品会尝试放回背包，背包满则留在原容器。
## 依赖
- **必需**：[Beyond Dimensions](https://modrinth.com/mod/beyonddimensions)
- 本模组不替代本体的网络终端、漏斗、泵等功能，只做「普通容器 → 维度网络」的轻量增强。
---
# Beyond Storage Addon (English)
An addon for **[Beyond Dimensions](https://modrinth.com/mod/beyonddimensions)** that adds a button and hotkeys on normal container screens to store items into a Dimension Network.
## Feature overview
- **Sort store**: plain `F` only stores items that already exist in the target network (by match mode).
- **Full store**: `Ctrl+F` and the GUI button store all eligible items.
- **Target network**: bind a specific Dimension Network ID.
- **In-game config**: `/bs_addon` commands write `config/beyondstorage.properties`.
- **Match modes**: same-item vs exact; container-like items stay stricter.
- **UI controls**: hide button / disable hotkey / fully disable quick-store by screen or menu class prefix; ignore hotkey while typing.
- **Safety**: server-side container checks, capacity simulation before extract, skip unsafe slots.
## Supported versions
Aligned with Beyond Dimensions:
| Minecraft | Loader | File |
| --- | --- | --- |
| 1.20.1 | Forge | `BS_addon_forge-1.20.1-1.3.0.jar` |
| 1.21.1 | NeoForge | `BS_addon_neoforge-1.21.1-1.3.0.jar` |
| 1.21.11 | NeoForge | `BS_addon_neoforge-1.21.11-1.3.0.jar` |
| 26.1.2 | NeoForge | `BS_addon_neoforge-26.1.2-1.3.0.jar` |
| 26.2 | NeoForge | `BS_addon_neoforge-26.2.0-1.3.0.jar` |
> 1.21.11 requires a matching Beyond Dimensions build (including alpha). Download the file that matches your game version and loader.
## How to use
### Install
1. Install **Beyond Dimensions** and this addon (**client and server**).
2. Open any normal container (chest, furnace, etc.).
3. Use the button, hotkeys, or commands below.
### Button & hotkeys
| Action | Default | Notes |
| --- | --- | --- |
| GUI **Full Store** button | Full store | Always full store; toggle with `showButton` / `/bs_addon button` |
| Plain `F` | **Sort store** | Only items already present in the target network; change with `/bs_addon mode normal` |
| `Ctrl+F` | **Full store** | All eligible items; change with `/bs_addon mode ctrl` |
Notes:
- Master hotkey toggle: `/bs_addon hotkey on|off` or `enableHotkey`.
- While a search/text field is focused, hotkeys are ignored by default (`ignoreHotkeyWhenTyping=true`).
- Per-screen lists can hide the button, disable the hotkey, or fully block quick-store (see config).
- Button visibility needs **reopening the container**; hotkey/target changes apply immediately.
- Server request cooldown defaults to 250 ms per player per container.
### Sort store vs full store
- **Sort store (`smart`)**: only move items the target network already has. Missing items try to return to the player inventory; if full they stay in the container — **no drop, no duplication**.
- **Full store (`all`)**: store every item allowed by the safe-slot policy.
- **Match mode** (sort store only):
- `same` (default): same item id counts as existing; protected container/storage-like items stay stricter.
- `exact`: item id and NBT/components must match.
### Target network
- Default `targetNetworkId=-1`: follow Beyond Dimensions **primary** network.
- `/bs_addon target set `: bind to a network id.
- `/bs_addon target clear`: clear binding.
- `/bs_addon target status`: show current binding.
### Commands (`/bs_addon`)
Client-side config commands; they write `config/beyondstorage.properties`.
| Command | Effect |
| --- | --- |
| `/bs_addon` or `/bs_addon help` | Show help |
| `/bs_addon status` | Button, hotkey, normal mode, ctrl mode, match mode |
| `/bs_addon button on` | Show the Full Store button (reopen container) |
| `/bs_addon button off` | Hide the button (reopen container) |
| `/bs_addon hotkey on` | Enable hotkeys |
| `/bs_addon hotkey off` | Disable hotkeys |
| `/bs_addon mode status` | Show F / Ctrl+F / match modes |
| `/bs_addon mode normal smart` | Plain `F` = sort store |
| `/bs_addon mode normal all` | Plain `F` = full store |
| `/bs_addon mode ctrl smart` | `Ctrl+F` = sort store |
| `/bs_addon mode ctrl all` | `Ctrl+F` = full store |
| `/bs_addon match same` | Sort store uses same-item matching |
| `/bs_addon match exact` | Sort store uses exact matching |
| `/bs_addon target status` | Bound id or primary network |
| `/bs_addon target set ` | Bind target network (`id` ≥ 0) |
| `/bs_addon target clear` | Clear binding |
| `/bs_addon debug current` | Print **last opened** Screen / Menu class names |
| `/bs_addon debug last` | Print **last store attempt** Screen / Menu class names |
Tip: open a problematic UI → run `/bs_addon debug current` → copy a stable package prefix into `hideButtonInScreens`, `disableHotkeyInScreens`, or `disableQuickStoreInContainers`.
## Config
File:
```text
config/beyondstorage.properties
```
Created automatically on first launch. Some keys can be changed via `/bs_addon`; others need editing this file.
### All keys
| Key | Default | Description |
| --- | --- | --- |
| `showButton` | `true` | Show the Full Store button. `/bs_addon button on\|off`. Reopen container after change. |
| `enableHotkey` | `true` | Enable hotkeys. `/bs_addon hotkey on\|off`. |
| `targetNetworkId` | `-1` | Network id for quick-store. `-1` = BD primary. `/bs_addon target set\|clear`. |
| `normalStoreMode` | `smart` | Plain `F`: `smart` = sort store, `all` = full store. `/bs_addon mode normal ...` |
| `ctrlStoreMode` | `all` | `Ctrl+F`: `smart` / `all`. `/bs_addon mode ctrl ...` |
| `existingItemMatchMode` | `same` | Sort-store matching: `same` or `exact`. `/bs_addon match ...` |
| `ignoreHotkeyWhenTyping` | `true` | Ignore hotkeys while a text field is focused. |
| `hideButtonInScreens` | (empty) | Screen/Menu class-name prefixes that **hide the button**. Comma or semicolon separated. Example: `net.p3pp3rf1y.sophisticatedstorage.` |
| `disableHotkeyInScreens` | (empty) | Prefixes that **disable the hotkey**. Same syntax. |
| `storePlayerInventory` | `false` | Also store from the player's own inventory slots while a container is open. Off by default. |
| `requireSlotMayPlace` | `true` | Only move slots that can accept the same item back. Avoids unsafe machine output/virtual slots. Keep enabled. |
| `requestCooldownMs` | `250` | Per-player per-container cooldown in ms (0–5000). Raise on high-latency servers. |
| `disableQuickStoreInContainers` | `com.wintercogs.beyonddimensions.` | Prefixes that **fully block** quick-store (button, hotkey, and server requests). Defaults to BD’s own UIs. Legacy key `blockedContainerClassPrefixes` is still read. |
Prefix matching:
- Matches the Screen/Menu class name and its superclasses by prefix.
- Separate multiple prefixes with `,` or `;`.
- Prefer `/bs_addon debug current` to discover class names.
Built-in safety (no config required):
- Skips player inventory by default, BD containers, non-pickup slots, and unsafe output/virtual slots.
- Simulates network capacity before extract; leftover stacks return to the original slot.
- Sort store never drops or duplicates items that the network does not already have.
## Dependencies
- **Required**: [Beyond Dimensions](https://modrinth.com/mod/beyonddimensions)
- This addon does not reimplement BD’s terminals, funnels, or pumps — it only speeds up container → network storage.