智能背包与存储
(slimefun-smart-device-addon)
Slimefun 智能存储附属:复刻精妙背包和精致存储,随身智能容器与统一存储网络终端,支持 Folia
Slimefun
Management
Storage
Technology

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),缺失会在启动时明确报错
Java21
构建Maven,mvn clean package(产物 target/SlimefunSmartDeviceAddon v1.0.0.jar)

把产物 jar 放进服务端 plugins/ 后重启即可,无需额外配置。所有 7 个物品都在 Slimefun 指南的 「智能设备」 分组里,配方均为增强工作台 3×3 有序合成。


五分钟上手

  1. 合成 1 个智能存储交互终端(侦测器外观)和若干连接器(末地烛外观,一次合成 8 个)。
  2. 在交互终端旁边放一个连接器,再从连接器往外接第二个、第三个……把箱子 / 木桶贴着连接器摆好。
  3. 右键交互终端 → 打开统一存储界面。第一个打开它的玩家会自动成为管理员。
  4. 合成智能背包,第一次使用会要求输入名称;之后手持背包右键任意箱子即可整箱装载。
  5. 想让搬运自动化:在连接器网络旁放卸载 / 加载终端,空手右键打开配置页设好过滤,再手持背包右键终端即可一键搬运。
  6. 想随身访问网络:合成无线交互终端,右键交互终端并输入名称完成绑定,之后手持右键即可打开同一个界面。

右键任意一个连接器可以开关整条链的红色粒子可视化,用来确认网络连到了哪里。


物品与合成配方

所有配方均为增强工作台 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.pom

Windows 下仓库另附一键脚本 deploy.ps1 / deploy.bat:编译 → 停服 → 复制 jar → 重启 → 等待端口就绪。

.\deploy.bat                 # 完整流程(推荐)
.\deploy.ps1 -NoRestart      # 只编译 + 复制,不重启
.\deploy.ps1 -SkipBuild      # 跳过编译,部署已有 jar
.\deploy.ps1 -DeploySlimefun # 同时部署本地 Slimefun fork 构建出的 jar

pom.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.ymlpush / PR 到 master构建检查,不出包
release.ymlv* 标签 / 手动构建并发布 Release,附带 jar


本项目采用 GPL-3.0 许可证开源。

Compatibility
Minecraft versions
26.3
26.2
26.1.x
1.21.2-1.21.11
Platforms
Folia
Paper
Tags
Slimefun
Management
Storage
Technology
Owner
Details
License
Updated
Created