快速存储 - Fabric

快捷存放（Quick Stash）

Quick Stash 是一个轻量级的 Fabric 模组，其灵感来源于《Grounded》等游戏中的快速存放系统。

只需按下一个按键，即可将匹配的物品自动存入附近符合条件的容器中。

Quick Stash 的设计初衷是让单人世界使用起来简单便捷，同时给予服务器管理员足够的控制权，以便为多人游戏和大型服务器调整后台可用性检测。

功能特性

• 一键快速存放
• 默认按键：R
• 可在 Minecraft 控制设置中更改按键绑定
• 支持：
  • 箱子
  • 大型箱子
  • 陷阱箱
  • 木桶
• 精确的物品与数据组件匹配
• 优先填充兼容的堆叠（非满组），然后才使用空槽位
• 只会将物品存入在操作开始前就已包含同类兼容物品的容器中
• 未匹配的物品会保留在玩家物品栏中
• 服务端权威的物品转移
• 支持多人游戏
• 成功音效与细微粒子反馈
• 快捷栏上方可用性提示
• 支持英语、西班牙语、阿根廷西班牙语和巴西葡萄牙语

Quick Stash 的工作原理

Quick Stash 不会自动整理、排序或分类你的存储容器。

只有当附近的某个容器在 Quick Stash 操作开始前就已经包含完全相同的、可兼容堆叠的物品时，该容器才有资格接收此类物品。

示例：

如果附近的箱子里已经有圆石，Quick Stash 就可以将更多兼容的圆石存入该箱子。

如果附近没有受支持的容器包含该物品，那么该物品将留在你的物品栏中。

在存放物品时：

1. 首先填充兼容的堆叠（非满组）。
2. 剩余物品可使用符合条件的容器中的空槽位。
3. 没有有效存放目标的物品将保持不变。

物品栏行为

Quick Stash 有意采用保守的物品栏策略。

只有主物品栏的 9–35 槽位会被考虑进行自动存放。

以下槽位会被排除在外：

• 快捷栏
• 当前选中的槽位
• 盔甲栏
• 副手

这有助于防止重要装备或正在使用的物品被意外移动。

多人游戏与服务端权威

Quick Stash 采用服务端权威的机制。

客户端仅发送 Quick Stash 操作请求。

由服务端决定：

• 哪个玩家发起了该操作
• 哪些附近的容器是有效的
• 哪些物品有资格被存放
• 物品如何被转移
• 操作后的物品栏状态

客户端不会发送容器位置、物品数据或转移结果。

服务端配置

首次启动时，Quick Stash 会创建：

config/quickstash.properties

默认配置如下：

automatic_hints_enabled=true
availability_check_interval_ticks=60
max_availability_checks_per_tick=8
availability_cache_ttl_ticks=120
search_radius=6
movement_threshold=1.5
deposit_cooldown_ticks=10

时间均以游戏刻（server tick）为单位。

Minecraft 通常每秒运行 20 个游戏刻。

修改配置后需要重启服务器。

配置选项

automatic_hints_enabled

默认值：true

启用或禁用用于“你有物品可以存放”快捷栏提示的后台自动检测。

设置为 false 时：

• 不会执行周期性的可用性扫描
• 自动提示被禁用
• 手动 Quick Stash 功能仍然正常工作
• 存放音效、粒子、消息和冷却时间依然生效

对于希望彻底消除 Quick Stash 后台扫描工作的服务器，可以禁用此选项。

availability_check_interval_ticks

默认值：60

最小值：20

最大值：72000

控制两次可用性检查之间的目标间隔。

调度器会将检查分散到不同的游戏刻中执行，而不是在同一个时刻检查所有在线玩家。

此间隔是一个目标节奏，并不是严格的保证。在玩家数量庞大的服务器上，调度器可能会拉长整个检查周期，以遵守每游戏刻的安全上限。

max_availability_checks_per_tick

默认值：8

最小值：1

最大值：16

限制在单个游戏刻内可计划的玩家可用性检查数量。

Quick Stash 还强制执行每游戏刻最多 16 次检查的内部硬上限。

这有助于防止过激的配置值或大量玩家造成同步的可用性检查峰值。

availability_cache_ttl_ticks

默认值：120

最小值：1

最大值：72000

控制在需要进行安全性刷新之前，缓存的可用性状态可以复用多长时间。

当满足以下条件时，Quick Stash 会避免进行不必要的完整附近容器扫描：

• 玩家相关的物品栏未发生变化
• 玩家移动距离未超过配置的移动阈值
• 玩家没有切换维度
• 缓存的扫描结果仍然有效

该 TTL 提供定期的安全性刷新，即使在玩家保持静止时，也能检测到附近容器发生变化。

search_radius

默认值：6

最小值：1

最大值：10

控制 Quick Stash 搜索受支持容器的范围。

数值越大，需要检查的世界数据就越多。

对于大型服务器，除非确实需要更大的搜索半径，否则建议保持默认值。

movement_threshold

默认值：1.5

最小值：0

最大值：4

控制玩家移动多大距离后，其缓存的可用性状态将被视为过期。

设置为 0 时，完全静止的玩家仍然可以复用缓存状态，而任何实际移动都会使基于移动的缓存失效。

deposit_cooldown_ticks

默认值：10

最小值：1

最大值：200

控制手动 Quick Stash 请求的服务端冷却时间。

默认的 10 个游戏刻大约是半秒钟。

推荐的大型服务器配置

对于大型多人服务器，一个保守的初始配置是：

automatic_hints_enabled=true
availability_check_interval_ticks=100
max_availability_checks_per_tick=8
availability_cache_ttl_ticks=160
search_radius=6
movement_threshold=1.5
deposit_cooldown_ticks=10

对于优先考虑最大程度减少所有自动后台工作的服务器：

automatic_hints_enabled=false

禁用自动提示后，手动 Quick Stash 功能仍然完全可用。

性能与可扩展性

Quick Stash 不会一次性对所有在线玩家进行一次大规模检查。

可用性工作会通过一个确定性的轮询调度器分散到各个游戏刻中执行。

例如，如果有 200 名在线玩家且默认间隔为 60 刻，检查会分散到多个游戏刻中，而不会一次性批量检查 200 名玩家。

该调度器还会：

• 限制每游戏刻的检查数量
• 保持玩家间的公平性
• 安全处理玩家加入和断开连接
• 在玩家数量变化时按比例调整累积的调度信用额度
• 防止玩家频繁加入/离开导致可用性检查被饿死

在执行完整的附近容器扫描之前，Quick Stash 会先执行开销较低的物品栏检查。

它只对与 Quick Stash 相关的物品栏槽位进行指纹识别，并在玩家状态没有实质变化时复用缓存的可用性数据。

附近容器搜索使用预先计算的球形偏移量，并跳过未加载的区块。

所有世界和物品栏的访问都保持在正常的服务器线程上执行。

Quick Stash 不会执行不安全的异步世界或物品栏访问。

对于规模非常大或包含大量模组的服务器，管理员应使用 Spark 或其他 Minecraft 性能分析工具来评估其实际环境。

建议测试的场景包括：

• 50 名玩家
• 100 名玩家
• 200 名模拟玩家
• 存储密集型基地
• 大量附近容器
• 玩家分散在不同维度
• 自动提示启用与禁用状态的对比

Quick Stash 不承诺有保证的玩家数量上限，因为实际性能取决于服务器硬件、其他模组、加载的实体、世界活动以及存储布局。

自动可用性提示

当启用自动提示时，Quick Stash 可能会显示：

你有物品可以存放

只有当物品栏中至少有一个物品可以实际存入附近有剩余空间的受支持容器时，该提示才会出现。

该提示会感知当前状态，并且不会在相同可用性状态持续时反复刷屏。

在搜索半径边界附近还应用了防抖处理。

环境要求

• Minecraft 1.21.1
• Fabric Loader 0.16.14 或更高版本（0.16 系列）
• Fabric API 0.116.5+1.21.1
• Java 21

安装方法

1. 安装 Fabric Loader。
2. 安装 Fabric API。
3. 将 Quick Stash 的 JAR 文件放入 mods 文件夹。
4. 启动 Minecraft 或服务器。

对于多人游戏，请在客户端和服务端均安装 Quick Stash。

当前限制

• 仅支持原版箱子、陷阱箱和木桶
• 目前不支持模组容器
• 无自动整理或存储重排功能
• 无分类规则
• 无自动容器分配
• 无过滤器或黑名单
• 无自定义物品栏界面
• 无容器覆盖层

重要说明

Quick Stash 旨在加快重复性存储管理操作，而不会接管你对存储布局的控制权。

它只会将匹配的物品存入已经包含这些物品的存储容器中。

它不会重新整理你的箱子，也不会在容器之间移动物品。