SlimefunSmartDeviceAddon · 智能存储
把「精妙背包」的随身容器手感,和「精致存储」的统一网络终端,一起带进 Slimefun。
一个 Slimefun4 附属插件 · 随身智能容器 + 统一存储网络终端 · 支持 Folia · 完整简体中文。
特性速览
- 随身容器:智能背包 54 格、容量条可视化、手持右键批量装载原版容器、快捷存入;智能小冰柜只装 Slimefun 果汁并自动补给。
- 统一存储网络:连接器泛洪组网(最多 32 容器),交互终端聚合为 9×6 分页 GUI,统一网格 / 排序 / 搜索 / 标记视图 / 三种整理。
- 装卸与无线:加载 / 卸载终端批量搬运容器,无线交互终端远程访问网络。
- 权限系统:容器与终端可配置访问权限。
- Folia 支持:区域 / 实体安全调度,已在 Folia 实机验证。
下载与反馈
- 下载:GitHub Releases
- Bug 反馈 / 建议:GitHub Issues
它能做什么
随身容器
- 54 格便携容器,物品图标上直接画出
已用 / 54的容量条,Lore 里还有进度条 - 手持时右键原版容器(箱子 / 陷阱箱 / 木桶 / 漏斗 / 发射器 / 投掷器 / 潜影盒)批量装载,自动合并同类堆叠;潜行右键则正常开箱
- 在物品栏里左键「用容器点物品」快捷存入,右键直接打开;支持切换多个已打开的容器
- 智能小冰柜只装 Slimefun 果汁:饱和度低于 2 时自动喝一瓶,余量 ≤ 3 时告警,扫描整份背包而不占用快捷栏
- 与 Slimefun 官方背包体系打通:内容存于
PlayerBackpack,合成时用官方COOLER/RADIANT_BACKPACK(辐射背包)升级并继承旧背包内容
网络化存储
- 连接器沿 6 个面泛洪成链,把相邻箱子 / 木桶聚合成一个网络,最多 32 个容器(大箱子算 1 个)
- 交互终端提供统一 GUI:一页 40 种物品,左击取一组、右击取一个、Shift 点击直接进背包、光标持有物品点击即存入
- 6 种排序、纸标记视图(显示每种物品在各容器的分布与距离)、容量监控、三种整理 / 压缩模式
- 每 20 tick 用库存指纹比对刷新,漏斗与货运改动会实时反映到界面,且只在真正变化时才重绘
- 加载 / 卸载终端给背包与网络之间加了一条可配置的自动化通道:容器内叠加 / 背包内叠加 / 黑名单 / 白名单,40 格过滤栏,标签精细匹配
- 无线交互终端绑定后,随时随地打开同一个网络界面
工程上的讲究
- 完整适配 Folia:读方块走区域线程、GUI 与消息走玩家实体线程、全局定时器只派单
- 全中文物品名(内置 2811 条官方简中映射),改过名的 Slimefun 物品也优先显示自定义名
- 认真处理了刷物品与幽灵物品:配方产出与掉落数量分离、破坏终端掉落过滤栏物品、创造模式占位物精确回收
环境要求与安装
| 项目 | 要求 |
|---|---|
| 服务端 | Canvas / Folia(推荐)/ Paper / Spigot |
| 前置 | Slimefun(plugin.yml 中为硬依赖) |
| Slimefun 版本 | 需要支持 Folia 的较新的 DEV / RC-36+ 版本:代码依赖 PlayerBackpack#getAsync(ItemStack),缺失会在启动时明确报错 |
| Java | 21 |
| 构建 | Maven,mvn clean package(产物 target/SlimefunSmartDeviceAddon v1.0.0.jar) |
把产物 jar 放进服务端 plugins/ 后重启即可,无需额外配置。所有 7 个物品都在 Slimefun 指南的 「智能设备」 分组里,配方均为增强工作台 3×3 有序合成。
五分钟上手
- 合成 1 个智能存储交互终端(侦测器外观)和若干连接器(末地烛外观,一次合成 8 个)。
- 在交互终端旁边放一个连接器,再从连接器往外接第二个、第三个……把箱子 / 木桶贴着连接器摆好。
- 右键交互终端 → 打开统一存储界面。第一个打开它的玩家会自动成为管理员。
- 合成智能背包,第一次使用会要求输入名称;之后手持背包右键任意箱子即可整箱装载。
- 想让搬运自动化:在连接器网络旁放卸载 / 加载终端,空手右键打开配置页设好过滤,再手持背包右键终端即可一键搬运。
- 想随身访问网络:合成无线交互终端,右键交互终端并输入名称完成绑定,之后手持右键即可打开同一个界面。
右键任意一个连接器可以开关整条链的红色粒子可视化,用来确认网络连到了哪里。
物品与合成配方
所有配方均为增强工作台 3×3 有序合成。表中「上排 / 中排 / 下排」各 3 格,用 · 分隔。
| 物品(产出) | 外观 | 上排 | 中排 | 下排 | 产出 |
|---|---|---|---|---|---|
| 智能小冰柜 | 收纳袋 | 布 · 合成蓝宝石 · 布 | 焊锡锭 · 冰柜 · 焊锡锭 | 16K 金锭 · 高级电路板 · 16K 金锭 | ×1 |
| 智能背包 | 收纳袋 | 布 · 合成蓝宝石 · 布 | 焊锡锭 · 辐射背包 · 焊锡锭 | 16K 金锭 · 高级电路板 · 16K 金锭 | ×1 |
| 智能存储连接器 | 末地烛 | 焊锡锭 ×3 | 焊锡锭 · 漏斗 · 焊锡锭 | 焊锡锭 · 电动马达 · 焊锡锭 | ×8 |
| 智能存储交互终端 | 侦测器 | 焊锡锭 · 高级电路板 · 焊锡锭 | 货运马达 · 侦测器 · 货运马达 | 24K 金锭 · 电动马达 · 24K 金锭 | ×1 |
| 智能存储背包卸载终端 | 炼药锅 | 黄铜锭 · 基础电路板 · 黄铜锭 | 电动马达 · 磁石 · 电动马达 | 24K 金锭 · 货运马达 · 24K 金锭 | ×1 |
| 智能存储背包加载终端 | 投掷器 | 银铜锭 · 基础电路板 · 银铜锭 | 电动马达 · 投掷器 · 电动马达 | 24K 金锭 · 货运马达 · 24K 金锭 | ×1 |
| 智能存储无线交互终端 | 末影之眼 | 焊锡锭 · 高级电路板 · 焊锡锭 | 货运马达 · 末影之眼 · 货运马达 | 24K 金锭 · 末地烛 · 24K 金锭 | ×1 |
材料对照:除加粗项为原版方块外,其余均为 Slimefun 物品 —— 布 CLOTH、合成蓝宝石 SYNTHETIC_SAPPHIRE、焊锡锭 SOLDER_INGOT、16K / 24K 金锭 GOLD_16K / GOLD_24K、基础 / 高级电路板 BASIC_CIRCUIT_BOARD / ADVANCED_CIRCUIT_BOARD、电动马达 ELECTRIC_MOTOR、货运马达 CARGO_MOTOR、黄铜锭 BRASS_INGOT、银铜锭 BILLON_INGOT、冰柜 COOLER、辐射背包 RADIANT_BACKPACK(Slimefun 最高级 54 格背包)。
为什么连接器是 ×8:配方产出单独设为 8 个,而物品模板本身仍是 1 个。Slimefun 破坏方块时掉落的是物品模板,若把模板数量改成 8,就会出现「放置 1 个、破坏掉 8 个」的无限刷物品。两者分离后,合成给 8 个、破坏只掉 1 个。
随身容器:智能背包 / 智能小冰柜
两者共用同一套容器逻辑,容量均为 54 格(Bukkit 与客户端 generic_9x6 的硬上限)。
| 行为 | 智能背包 | 智能小冰柜 |
|---|---|---|
| 可装物品 | 绝大多数物品(拒绝潜影盒与其它背包,防止套娃) | 仅 Slimefun 果汁 |
| 自动功能 | — | 饱和度 < 2 时自动饮用一瓶果汁,恢复至 6;余量 ≤ 3 时告警 |
| 首次使用 | 需在聊天里输入名称完成初始化(约 30 秒内完成绑定检测) | 同左 |
操作速查
| 操作 | 效果 |
|---|---|
| 物品栏中右键容器 | 打开 54 格容器 GUI |
| 物品栏中左键「用容器点物品」 | 收纳袋式快捷存入,放不下的部分退还 |
| 手持容器右键原版容器 | 批量装载,先补同类非满堆叠、再用空槽;按源槽实际可放数量扣减 |
| 手持容器 + 潜行右键原版容器 | 不接管,正常打开那个箱子 |
| 手持背包右键交互终端 | 扫描整个网络批量装载(受该终端 ACL 校验) |
| 手持背包右键卸载 / 加载终端 | 执行配置好的搬运 |
容量可视化:物品材质固定为收纳袋,用 BundleMeta 画容量条;已绑定时显示 已用 / 54,未绑定时用 64 个冰占位盖掉原版 tooltip。Lore 里同步显示进度条与 used/54。1.20.5+ 走反射写入 max_stack_size 组件,1.19.2 退回 64 权重映射,两代客户端都能正确显示。
存储网络:连接器
- 组网:交互终端 6 邻格中的连接器为入口(距离 1),连接器沿上下左右前后 6 面 BFS 泛洪,距离 = 经过的连接器个数。箱子是叶子节点,不会把两条独立的链合并。
- 容器范围:只认原版
箱子 / 陷阱箱 / 木桶,且排除所有 Slimefun 方块。上限 32 个容器(大箱子算 1 个),连接器链本身有 512 个的防御性上限。 - 大箱子:Paper/Folia 的
Block#getState()返回快照,只能拿到半边 27 格;因此优先反射调用getState(false)拿实时状态,Spigot 1.19.2 无该重载时退回旧接口。两半会去重成同一个 54 格库存,标签前缀「大」。 - 存取顺序:存入按容器距离升序、槽位正序(先补非满堆叠、再用空槽);取出按距离降序、槽位倒序(从最远的箱子先拿)。匹配一律用
ItemStack#isSimilar(显示名、附魔、耐久、NBT 全一致)。 - 可视化:右键任意连接器,整条连通链一起开关红色 DUST 粒子,状态写入 BlockStorage 并跨重启保留;每 10 tick 绘制一次,绘制范围自动收束到「最后一个挂了箱子的连接器」,每 40 tick 重算一次以跟上箱子增减。
- 红石隔离:交互接口方块本身永远不接受红石、漏斗与 Slimefun 货运。
交互终端 GUI
一个 9×6 = 54 格的分页界面。第一行是功能按钮,第一列为黑玻璃,剩下 5 行 × 8 列 = 40 格是展示区。
| 槽位 | 按钮 | 说明 |
|---|---|---|
| 0 | 显示标记和位置 | 切换「紧凑视图 / 纸标记视图」,按方块持久化 |
| 1 | 排序 | 6 种模式循环切换,按方块持久化 |
| 2 | 容量监控 | 只读:已用百分比、20 段进度条、各容器已用槽数 |
| 3 | 权限管理 | 打开权限页 |
| 4 | 压缩整理 | 尽量把近处容器填满,来源优先取最远容器 |
| 5 | 整理物品(跨容器) | 容器内整理后,把远处散堆叠补进近处已有同类堆叠 |
| 6 | 整理物品(每个容器内) | 逐箱合并同类、紧凑排布,物品绝不跨箱 |
| 7 / 8 | 上一页 / 下一页 | 翻页 |
6 种排序:容器距离升序(默认)、容器距离降序、创造物品栏、物品数量降序、物品数量升序、物品 ID 升序。
两种视图
- 紧凑视图(默认):一页 40 种,物品格数量 = 网络内真实总数(可超过 64),标题带
× 总数。 - 纸标记视图:一页 20 种,每种占相邻两格 —— 左边是物品本身,右边是纸标记,纸的数量表示组数(最多叠 64 张,真实组数写在 lore 里,不会被截断),并逐容器列出分布与距离。两格点击行为完全一致。
点击速查
| 操作 | 效果 |
|---|---|
| 左击物品格 / 标记格 | 取出一组到光标 |
| 右击 | 取出一个 |
| Shift + 左击 | 取一组直接进背包 |
| Shift + 右击 | 取一个直接进背包 |
| 光标持有物品时点击界面 | 把光标整叠存入网络,只存了部分时剩余退回光标 |
| Shift 点击玩家背包里的物品 | 批量存入网络 |
顶部 54 格一律取消原版交互,取出的物品优先写光标,背包满则掉落在脚边。每次点击前会用库存指纹核对,避免漏斗刚搬走物品导致点空。
实时刷新:打开期间每 20 tick 比对一次指纹,有变化才重绘(避免整屏闪烁);每 100 tick 完整重发现一次网络。箱子被拆会当场从网络剪掉,防止把物品写进已脱离世界的方块实体。
权限子页面:第 2 行起 5 行 × 9 列 = 45 个玩家头颅 / 页,左击切换管理员 / 普通成员、右击删除;只有管理员可改,且不能删除或改动自己。添加玩家页按名字排序列出所有在线玩家。移除成员后,仍开着界面但已失去权限的玩家会被当场踢出。
加载 / 卸载终端
放置后的方块,手持背包右键执行搬运;空手或手持其它物品右键打开 9×6 配置页。
配置页第一行是 4 个开关(模式 / 匹配标签 / 加载范围(仅加载终端)/ 权限状态),下方 40 格过滤栏不分页。过滤格里的物品只是模板:数量一律归一为 1,多出来的返还玩家,配置按方块持久化到 BlockStorage(Base64 序列化)。
| 终端 | 可用模式 | 说明 |
|---|---|---|
| 卸载终端 | 容器内叠加(默认)· 黑名单 · 白名单 | 把背包物品搬进网络容器 |
| 加载终端 | 背包内叠加(默认)· 黑名单 · 白名单 | 把网络物品搬进背包 |
- 容器内叠加 / 背包内叠加:动作开始前从网络容器(或背包)实时快照出白名单,只搬运「那边已经有了」的种类。
- 黑名单 / 白名单:以 40 格过滤列表为准。
- 匹配标签(默认开):开启用
isSimilar(附魔、耐久、显示名、NBT 全一致);关闭只比对物品 ID。 - 加载范围(仅加载终端):默认「加载至满堆叠」,只补满背包已有堆叠、不新占空槽;可切到「加载所有」,允许使用空槽。
搬运行完会给详细回执:共 N 个物品、M 种,逐行列出中文名与数量(最多 20 种),网络已满时提示已提前停止。
终端被玩家敲掉时,40 格过滤栏里的物品会全部掉落到地面,并清理仍指向该方块的配置会话。这是通过 Slimefun 的
BlockBreakHandler在清除方块数据之前读取的,用普通的破坏事件监听会读不到数据。
无线交互终端
- 不可放置的手持物品。右键一个已放置的交互终端,在聊天里输入 1~24 字名称即可绑定;物品显示名会变成
名称 [无线存储终端]。 - 绑定后手持 / 物品栏右键即可打开与右键终端完全相同的存储界面(含权限校验)。
- 没有距离与维度限制:跨世界、远距离都可以打开,唯一要求是目标世界已加载、且该坐标仍是交互终端。
- 若绑定的方块被破坏或替换,下一次使用会自动解除绑定并提示重新绑定。重新右键另一个终端即可覆盖旧绑定。
- 绑定期间切换手持物品会取消本次绑定(而不是补发一个已绑定终端)—— 这是专门修掉的刷物品漏洞。
权限系统
分两层,ACL 是唯一数据源,不存角色快照,改完立即生效。
每个交互终端自己的 ACL:存在该方块的 BlockStorage 里,角色分 管理员 / 普通成员。第一个打开(且尚无管理员)的玩家自动成为管理员;之后不在名单里的玩家打不开界面。管理员可增删成员、切换角色,但不能删除或改动自己。
全局权限(供加载 / 卸载终端使用):终端没有自己的权限页,复用交互终端 ACL —— 只要在任意一个已放置的交互终端上是成员,就能对任意加载 / 卸载终端执行搬运;只有在某个交互终端上是管理员,才能修改终端配置页。已知交互终端坐标持久化在插件数据目录的 smart-storage-terminals.txt,终端执行动作时会沿连接器网络 BFS 自愈补齐(覆盖重启 / 老存档)。区块未加载时只跳过、绝不删坐标,避免权限莫名失效。
配置页人人可查看,非管理员整页只读(连玩家背包 Shift 点击都拦截)。
配置项
所有可调参数都集中在 plugins/SlimefunSmartDeviceAddon/config.yml,改完重启生效。源码里不再保留调优用的常量:启动时由 AddonSettings 一次性读取并缓存,运行期只读、Folia 各线程安全;删掉某个键会退回内置默认值。
options:
debug: true # 给玩家发调试消息,正式发布建议 false
smart-storage-lock-external-transfers: false
network:
max-containers: 32 # 单条链最多聚合的容器数
max-connectors: 512 # 一次泛洪 / 可视化最多遍历的连接器数
connector-particle-period-ticks: 10 # 红色粒子刷新周期
interface:
refresh-period-ticks: 20 # 交互终端刷新周期
full-rediscover-every: 5 # 每隔几轮做一次全量重发现
wireless-terminal:
max-name-length: 24 # 绑定名称最大字符数
container:
backpack-stack-multiplier: 1 # 智能背包单格堆叠系数
cooler-stack-multiplier: 1 # 小冰柜单格堆叠系数
creative-action-dedup-millis: 250 # 创造模式点击去重窗口
creative-leak-window-millis: 15000 # 占位物泄漏回收窗口
init-watch-period-ticks: 10 # 首次命名监视器检查周期
init-watch-max-checks: 60 # 首次命名监视器最大检查次数
cooler:
saturation-threshold: 2.0 # 低于此饱和度自动喝果汁
saturation-restore: 6.0 # 喝完后恢复到的饱和度
feed-cooldown-millis: 2000 # 两次自动饮用之间的冷却
check-interval-ticks: 10 # 自动饮用轮询周期
low-juice-warning-below: 3 # 剩余果汁低余量提示阈值(0 = 关闭)smart-storage-lock-external-transfers 控制交互界面「打开期间」是否冻结已连接容器的外部搬运(漏斗 / Slimefun 货运结点):false(默认)时界面按 interface.refresh-period-ticks 实时刷新,漏斗与货运照常工作、显示自动跟上;true 时拦截外部搬运,保证看到的数量与点击结果严格一致,但自动化会短暂停摆。无论怎么设置,交互接口方块本身永远不接受红石 / 漏斗 / 货运。
结构性常量(GUI 54 格与槽位、分页布局、过滤栏 40 格、物品 ID、PDC 键、材质、文案)仍留在代码里 —— 它们与界面布局 / 存档格式绑定,做成可配置会直接破坏功能。文中出现的 32 个容器、20 tick、54 格等数值均指上述默认值。
其余状态都按方块存在 Slimefun 的 BlockStorage:连接器可视化开关、显示标记开关、排序模式、交互终端 ACL、终端的模式 / 匹配标签 / 加载范围 / 过滤栏。
技术设计
Folia 线程模型(model/ResourceLib 统一封装)
| 工作 | 线程 |
|---|---|
| 网络发现、读方块状态、粒子发射 | 方块所属区域线程(runAtBlock / runAtLocation) |
GUI 渲染、点击处理、openInventory、发消息、实体状态改动 | 玩家实体线程(runAtEntity) |
| 全局定时器 | 只派单,不碰世界 |
| 页面切换、强制重绘、过滤栏归一化 | runAtEntityLater(player, 1L) |
缓存到的 Inventory 包着真实方块实体,getItem/setItem 无区域线程断言,所以取 / 存 / 整理都能同步完成,无异步延迟。依赖 FoliaLib 0.5.1,通过 maven-shade 重定位到 me.cyantangerine.slimefunaddon.lib.folialib。
库存指纹:把网络聚合成「一种物品一行」的只读快照,指纹覆盖容器集合、每组模板 hash / 总数 / 每箱分布、空槽数。既能发现外部搬运,又不会因同类物品在箱内换格子而误判重绘。点击后 1 tick 强制重绘,用来盖掉服务端取消点击后客户端重发的旧槽位包。
中文物品名:服务端通常只有 en_us.json,Material#name() 会得到 DIAMOND。插件内置 2811 条官方简中映射(2000 条方块 + 811 条物品),按 isBlock() 选择前缀,读取时兼容 UTF-8 BOM 与 GB18030 回退。命名优先级为 自定义显示名 > Slimefun 物品名 > 原版中文名 > 材质名,所以改过名的背包 / 无线终端会显示玩家起的名字。
跨版本兼容:ItemMeta#setMaxStackSize(1.20.5+)与 1.19.2 的 64 权重映射双路径;Block#getState(false) 反射拿实时大箱子;Material#getCreativeCategory 反射取创造栏分类;VersionedParticle.DUST 兼容 1.19.2 的 REDSTONE 与新版 DUST;货运事件通过独立内部类以 FQN 引用,换回不含该事件的 Slimefun 版本也不会 NoClassDefFoundError。
防刷物品 / 防幽灵物品:配方产出与物品模板数量分离;破坏终端掉落过滤栏;无线终端绑定按精确槽位写回;创造模式点击产生的「幽灵占位物」用 PDC 标记 + 250 ms 去重 + 15 秒回收窗口精确回收,只删带标记的物品,不会误伤玩家自己的玻璃瓶或冰。
已知限制
- 网络必须放在同一个 Folia tick region 内:跨区域的容器会被跳过(只打一条一次性 WARN)。这是 Folia 区域线程模型的硬约束。
- 容器 GUI 上限 54 格,单格堆叠封顶 64:任何更大的自定义上限都会因客户端不认而在 GUI 同步 / 存档往返后整叠消失。
- 智能背包 / 冰柜堆叠系数默认为 1(与原版上限一致),可在
options.container.backpack-stack-multiplier/cooler-stack-multiplier调大;但单格上限仍封顶 64(见上一条客户端限制)。 - 暂无地面掉落物自动拾取:Lore 中的「收纳袋式」指物品栏内左键点入与手持右键容器批量装载,不含
EntityPickupItemEvent监听。 - 无线终端无距离 / 维度限制(见上文),这是有意为之。
- 升级合成依赖本地 Slimefun fork:冰柜 / 智能背包配方中心使用官方背包,走
upgradeBackpack继承语义;该路径在 Folia 上曾报Cannot read world asynchronously,已在 fork 中修复。 options.auto-update目前是预留开关,尚无实际更新逻辑。- 默认开启调试输出(
options.debug = true),会给玩家发送事件 / 点击类型等调试消息;正式发布前改为false。
构建与部署
mvn clean package
# 产物:target/SlimefunSmartDeviceAddon v1.0.0.jar若本地未缓存 Slimefun 的 DEV-SNAPSHOT,先把 lib/Slimefun-DEV-SNAPSHOT.jar 装进本地仓库。用随仓库提供的精简 POM(lib/Slimefun4-clean.pom),避免 jar 内嵌的 dough parent 解析失败:
mvn install:install-file -Dfile=lib/Slimefun-DEV-SNAPSHOT.jar ^
-DpomFile=lib/Slimefun4-clean.pomWindows 下仓库另附一键脚本 deploy.ps1 / deploy.bat:编译 → 停服 → 复制 jar → 重启 → 等待端口就绪。
.\deploy.bat # 完整流程(推荐)
.\deploy.ps1 -NoRestart # 只编译 + 复制,不重启
.\deploy.ps1 -SkipBuild # 跳过编译,部署已有 jar
.\deploy.ps1 -DeploySlimefun # 同时部署本地 Slimefun fork 构建出的 jarpom.xml 编译基准为 spigot-api 1.19.2、JDK 21;实际验证环境为 Folia / MC 26.3 API,并用 JDK 27 对真实 Folia API 做过 javac 校验。
自动发版
GitHub Actions 会自动打包并发布到 Releases,无需手动上传:
- 打标签发版:推送一个
v开头的标签即触发,例如git tag v1.0.1 && git push origin v1.0.1 - 手动发版:在仓库 Actions → Build & Release → Run workflow 里填入标签触发。
流水线用 JDK 21 构建,并先用仓库内 lib/Slimefun-DEV-SNAPSHOT.jar 安装到本地 Maven 仓库再打包——因为 Slimefun 的 Folia fork 在中央 / jitpack 上拉不到,直接 mvn package 会因缺少依赖而失败。因此 lib/ 下的 jar 需要随仓库一起保留。
两个 workflow 的分工:
| Workflow | 触发 | 作用 |
|---|---|---|
maven.yml | push / PR 到 master | 构建检查,不出包 |
release.yml | v* 标签 / 手动 | 构建并发布 Release,附带 jar |
本项目采用 GPL-3.0 许可证开源。