原创 - 工具 - RptShulkerBox —— 在背包内右键潜影盒即开，不用拿在手上 [1.21 ~ 26.2]

版权类型: 原创

插件中文名称: RPT快捷潜影盒

插件英文名称: RptShulkerBox

原帖地址: #

支持的核心（服务端）

Paper
Folia

语言支持: 中文（简体）

适配版本（Java）

26.x
1.21

关于这个插件

原版里想用潜影盒掏个东西，得走完「放地上 → 打开 → 拿东西 → 敲掉 → 捡起来」一整套操作。在生存服里翻战利品、整理材料时，这套动作每天要重复几十遍。
RptShulkerBox 把潜影盒变成随身容器：手持潜影盒右键一下直接打开，不放置任何方块、不改变世界、不产生掉落物。打开的是你手里那个潜影盒里的东西，关掉就自动写回，随时继续带走。
同时它把「打开」和「放置」分得很干净：右键方块默认仍是原版放置行为，想摆出来用照常摆，不会出现「一边打开界面、一边把方块放到地上」的混乱。

功能说明

1. 两种默认打开方式

方式	操作	配置项	默认
右键空气	手持潜影盒对着空气右键	`allow-interact-air`	开
背包内右键	在背包 / 合成界面里右键潜影盒	`allow-in-inventory`	开
右键方块	手持潜影盒对着普通方块右键	`allow-interact-block`	关
其它插件 GUI	在商店 / 菜单等第三方界面里右键潜影盒	`allow-in-other-gui`	关

四个场景互相独立，服主按服内习惯自由取舍。默认只开最实用的两种，不会干扰原版操作。

右键方块默认关闭，是为了保住原版的「放置潜影盒」。把它打开后，右键方块会改为打开潜影盒，此时右键方块不再放置，请按需选择。

2. 不落地、不改变世界

打开的是潜影盒物品本身装的东西，不会在世界里放下任何方块，也不会产生掉落物。
关闭界面时内容会自动写回物品，背包（或光标）里的那个潜影盒就是你刚编辑完的那一个。
支持全部 17 种潜影盒（普通潜影盒 + 16 种染色潜影盒）。
打开时会尊重潜影盒的自定义名字：给潜影盒改过名，界面标题就用你起的名字；没改过则用配置里的 gui-title。

3. 与原版操作不冲突

右键方块默认不拦截，原版放置潜影盒的行为完全保留。
只在主手触发的场景生效，副手不影响。
背包内右键只在指定场景拦截，其余点击一律放行，不干扰正常整理背包。
打开与关闭都带原版潜影盒音效（block.shulker_box.open / .close），音量与音高可调，也可以设为 NONE 彻底静音。
界面在下一个游戏刻才弹出，避开原版右键事件的处理时机，不会出现界面被立刻关掉或与原版动作打架的情况。

4. 打开冷却，防连点误触

cooldown-ms（默认 500，即 0.5 秒）内重复右键不会重复开箱，只提示「冷却中… 请稍后」。
避免玩家快速连点导致界面闪动、或与原版动作叠加。

5. 防盒套盒（潜影盒套潜影盒）

prevent-shulker-in-shulker（默认开启）会拦住「把潜影盒塞进正在打开的潜影盒里」的全部四条途径：
- 光标拿着潜影盒点进打开的盒子；
- Shift 点击把自己背包里的潜影盒快速移进打开的盒子；
- 用数字键把快捷栏的潜影盒换进打开的盒子；
- 用副手交换把潜影盒换进打开的盒子。
命中时直接拦截并提示「不能将潜影盒放入潜影盒内！」。
这一条能有效避免「潜影盒套娃」带来的物品丢失纠纷 —— 也是很多服主最在意的一点。

6. 打开期间禁止丢弃

正在打开状态下的那个潜影盒无法被丢出（Q 键 / 拖出界面都会拦住），提示「请先关闭潜影盒再丢弃！」。
目的是防止「丢出去 → 内容无处写回」造成的内容丢失。

7. 世界黑名单

disabled-worlds 里列出的世界里，打开相关的逻辑完全不介入：右键不会被拦截、不会打开界面、不会发拦截提示，全部走原版。
适合在副本、竞技场、活动地图等不想让玩家原地开背包的维度单独关掉。

8. ActionBar 操作提示（自带新手引导）

玩家切到手持潜影盒的快捷栏格子、或进服时主手拿着潜影盒，屏幕下方会显示一行提示（默认「右键空气打开潜影盒」）。
提示在 actionbar-duration（默认 1 秒）内每秒刷新一次，随客户端自身的淡出节奏显示；玩家一放下潜影盒就立即停止刷新，很快淡出，不刷屏。
不需要写教程公告，玩家拿到潜影盒自己就知道能右键打开。

9. 管理员指令：`/rpts list`

一条指令列出当前所有正在使用快捷潜影盒的玩家（含 UUID 前 8 位），排障时用来确认「是谁开着盒子」很方便。

10. 完全适配 Folia

已声明 folia-supported: true。
打开界面、ActionBar 刷新等涉及玩家状态的操作，全部通过 player.getScheduler() 调度到玩家自己的区域线程执行，不在错误线程里触碰玩家数据。
ActionBar 用 runAtFixedRate 按玩家区域调度，跨区域不做任何实体操作。

支持版本与环境

项目	说明
Minecraft 版本	1.21 ~ 26.2（插件 `api-version` 为 `1.21`）
实机验证	1.21.4 + Folia（本版已在该环境完成启动、加载与部署验证）
服务端核心	Paper、Folia（已声明 `folia-supported: true`）
Java 运行环境	Java 21 及以上
不支持	1.20.x 及以下（`api-version` 为 1.21，低版本核心会拒绝加载）
外部依赖	无。不依赖经济、数据库或任何其它插件

本版核心逻辑只用到了 1.21 起就存在的稳定 API（Registry.SOUNDS、player.getScheduler()、PersistentDataContainer 等），并对「老核心没有 Registry.SOUNDS」做了兜底降级（自动静音而不是报错）。若你在其它版本上遇到问题，欢迎到交流群反馈。

目标用户

生存服 / 生电服服主 —— 玩家随手掏材料、整理战利品时少掉一整套放置与破坏操作，同时世界里的方块数量不会因为开箱而变化。
在意物品纠纷的服主 —— 盒套盒防护 + 丢出拦截，把最容易扯皮的两种操作直接堵住。
正在使用 Folia 核心的服主 —— 涉及玩家状态的操作全部按区域线程调度，Folia 下不会因跨线程访问报错。
希望行为完全可控的服主 —— 四种打开场景、世界黑名单、冷却时长、音效、全部提示文案都能改，不需要的功能关掉就是原版行为。

是否付费

完全免费。不需要授权、不需要联网校验，下载即用。

获取作者帮助

途径	内容
交流群	QQ 群 1124248111
作者 QQ	2221899680
游戏内	输入 `/rpts help` 查看指令与说明（这条指令不需要权限）

使用教程

安装

将 RptShulkerBox-1.0.0.jar 放入服务端 plugins/ 目录。
重启服务端，首次启动会生成 plugins/RptShulkerBox/config.yml。
按需修改 config.yml 后，游戏内执行 /rpts reload 即可生效，不需要重启服务端。

指令列表

指令	权限	说明
`/rpts help`	无需权限	显示指令帮助与联系方式
`/rpts reload`	`rpts.admin`	重载 `config.yml`
`/rpts list`	`rpts.admin`	列出当前正在使用快捷潜影盒的玩家

主指令为 /rpts，别名 /rptshulkerbox、/rptshulker、/rptbox。
直接输入 /rpts（不带参数）等同于 /rpts help。
控制台也可以执行 /rpts、/rpts help、/rpts reload、/rpts list。

权限节点

权限	默认值	说明
`rpts.use`	所有玩家	使用快捷潜影盒（右键打开）
`rpts.admin`	仅 OP	重载配置 / 查看使用中的玩家

help 不需要任何权限，方便普通玩家看到交流群与作者联系方式。

主要配置项（config.yml）

打开场景开关

配置项	默认值	说明
`allow-in-inventory`	`true`	在玩家自己的背包 / 合成界面里右键潜影盒时打开
`allow-interact-air`	`true`	手持潜影盒右键空气时打开
`allow-interact-block`	`false`	手持潜影盒右键普通方块时打开（开启后右键方块不再放置潜影盒）
`allow-in-other-gui`	`false`	在第三方插件 GUI（商店、菜单）里右键潜影盒时打开
`cooldown-ms`	`500`	两次打开之间的冷却时间（毫秒）
`disabled-worlds`	`[disabled_world_1, disabled_world_2]`	不启用本插件的世界名单，请改成你自己的世界名，用不到就留空 `[]`

安全与外观

配置项	默认值	说明
`prevent-shulker-in-shulker`	`true`	禁止把潜影盒放进正在打开的潜影盒内
`gui-title`	`&f潜影盒`	容器界面标题（潜影盒自带自定义名字时优先用名字）
`actionbar-enabled`	`true`	是否显示手持提示
`actionbar-duration`	`1`	提示持续秒数
`actionbar-message`	`&e右键空气打开潜影盒`	提示内容
`open-sound` / `close-sound`	`block.shulker_box.open` / `.close`	开 / 关音效，填 `NONE` 表示静音
`open-volume` / `open-pitch`	`1.0` / `1.0`	开箱音量与音高
`close-volume` / `close-pitch`	`1.0` / `1.0`	关箱音量与音高

提示文案
messages: 段下的所有提示（冷却中、无权限、请先关闭再丢弃、重载成功、不能在容器内使用、不能盒套盒……）都能自定义，支持 & 颜色代码。

常见问题

右键没反应？按顺序确认四件事：① 是不是主手拿着潜影盒；② 右键的是空气吗（右键方块默认不触发，除非你把 allow-interact-block 打开了）；③ 有没有开着箱子/末影箱等容器界面（在容器里不触发）；④ 当前世界是不是被写进了 disabled-worlds。
想摆出来用怎么办？直接右键方块就是原版放置，插件默认不插手。
会不会把方块放到地上？不会。触发快捷打开时原版放置动作会被拦截，世界里不会多出方块。
提示「不能在容器或末影箱内使用快捷潜影盒」？你正开着箱子或别的容器界面。请先关掉容器，或把自己的背包（E 键）作为当前界面再右键潜影盒。
为什么不能把潜影盒放进打开的盒子里？这是 prevent-shulker-in-shulker 的默认行为，防止盒套盒造成物品纠纷。确实需要就把它设为 false。
关了界面东西还在吗？在。关闭界面会把内容写回该潜影盒。唯一要求是打开期间不要把这个潜影盒处理掉 —— 插件已经拦住了「丢出」和「塞进盒子」，正常操作不会丢。
改了 config.yml 为什么不生效？执行 /rpts reload（需要 rpts.admin）。
普通玩家能自己关掉这个功能吗？本插件不提供玩家自助开关，是否启用由服主通过配置与 rpts.use 权限统一控制。若只想给部分玩家开放，把 rpts.use 交给权限组即可。
disabled-worlds 里那两个世界是什么？是默认占位值（disabled_world_1 / disabled_world_2），通常并不存在，所以默认实际不屏蔽任何世界。请改成你的世界名，用不到就填 []。

声明

本插件为原创作品，保留所有权利，默认不允许转载与整合。如需转载或整合进服务端整合包，请先通过上方交流群或作者 QQ 联系获取授权。
本插件未使用任何混淆手段，欢迎安全审查。
本插件不含任何后门、病毒或远程控制代码，不收集任何玩家数据。

原创工具 RptShulkerBox —— 在背包内右键潜影盒即开，不用拿在手上 [1.21 ~ 26.2] 1.0.0

关于这个插件