原创 开源 工具 世界管理 [优化|管理|清理]⭐WorldListTrashCan⭐不只是清理插件-它会收集到玩家创建的垃圾桶 7.2.0

WorldListTrashCan-重构版 更新内容

一、公共垃圾桶

1. 新增 compact 紧凑显示模式
- 相同物品只显示一个图标。
- 在物品 Lore 中显示累计数量。
- 可限制原始 Lore 的最大显示行数。
- 超出行数后自动显示省略提示。
- 单种物品默认最多累计 9999 个。
- 设置为 -1 时不限制单种物品数量。
- 左键默认取出 1 个。
- Shift+左键默认取出 64 个。
- 取出数量可以在配置文件中调整。

2. 保留 stacked 原始堆叠模式
- 继续使用原版 64/16/1 的物品堆叠方式。
- compact 和 stacked 使用相互独立的配置节点。
- 两种模式的容量和排序设置互不干扰。

3. 重构公共垃圾桶存储
- GUI 不再作为公共垃圾桶的真实存储容器。
- 真实存储和菜单显示已经分离。
- 减少菜单刷新、翻页和物品合并带来的额外开销。
- 缩小容量时，已有物品会进入只读溢出页。
- 溢出物品仍然可以查看和取出，不会被静默删除。

4. 新增玩家独立排序
每名玩家可以独立选择以下排序方式：
- 进入顺序
- 数量升序
- 数量降序
- 名称排序
- 材质排序

排序偏好只保存在玩家本次在线期间，不写入数据库。
compact 和 stacked 模式分别保存自己的排序偏好。

5. 优化菜单刷新逻辑
- 排序只在打开菜单或玩家主动切换排序时执行。
- 翻页和取物使用打开菜单时生成的轻量快照。
- 扫地入库不会让玩家正在查看的页面突然重新排序。
- 不同玩家可以同时使用不同排序方式。

6. 扩展布局按钮
- 新增 type: close 关闭按钮。
- actions 新增 [close] 动作。
- 布局展示物支持 glow: true 附魔光效。
- 光效支持翻页、背景、排序、actions 和关闭按钮。
- 1.20.5+ 使用原生纯光效。
- 旧版本自动降级为隐藏附魔实现。

7. 修复 model-id
- Minecraft 1.14+ 正常读取和应用 CustomModelData。
- Minecraft 1.12.2 和 1.13 完全不读取、不解析该字段。
- 修复现代 Paper 上配置了 model-id 但按钮模型不生效的问题。
- CustomModelData 方法只在启动时探测和缓存一次，不在 GUI 热路径重复反射。


二、物品识别与扫地路由

1. 新增 /wtc look 查询功能
可以查看手持物品的：
- Material
- 物品名称
- Lore
- PDC key
- Raw NBT/Data Components key

用于帮助服主编写准确的物品匹配配置。

2. 新增自定义数据物品路由
可以按照以下内容识别物品：
- 材质
- 名称
- Lore
- PDC key
- Raw NBT/Data Components key

匹配规则支持 * 通配，并且不区分大小写。

3. 自定义物品可选择以下处理方式
- personal-only：只进入个人垃圾桶
- keep-ground：保留在地面
- direct-remove：直接删除

4. 新增公共垃圾桶准入白名单
公共垃圾桶可以按照以下内容限制允许进入的物品：
- 材质
- 名称
- Lore
- PDC key
- Raw NBT/Data Components key

白名单同时作用于：
- 扫地回收
- 玩家手动放入
- 其他插件调用公共垃圾桶接口

被公共垃圾桶拒绝的扫地物品可以配置为：
- 保留在地面
- 直接删除

5. 优化通配匹配性能
- 通配规则在加载配置时预编译。
- 扫地热路径不再重复解析相同规则。
- 未开启自定义数据路由时，不执行额外的 PDC 和 Raw NBT 检查。


三、扫地世界过滤

1. 新增 include/exclude 世界过滤
示例：

world-filter:
include:
- "*"
exclude:
- "*dungeon*"

2. 世界名支持 * 通配
- 不区分大小写。
- exclude 的优先级高于 include。
- 默认允许全部世界。
- 默认保护名称中包含 dungeon 的世界。

3. 世界过滤同时作用于
- 定时扫地
- /wtc clear true
- /wtc clear false

/wtc clear true 只会忽略人数和实体数量 guards，不会绕过世界过滤。


四、审计附属支持

1. 增加精确物品追踪键
- 公共垃圾桶中的每个真实存储条目都有独立追踪键。
- 个人垃圾桶中的同源物品也可以被准确追踪。
- 排序、翻页和显示模式不会改变追踪关系。

2. WorldListTrashCanAudit 可以进一步确定
- 物品最终进入了哪个垃圾桶。
- 公共垃圾桶物品被谁取走。
- 个人垃圾桶物品是否被取走。
- 世界垃圾桶所属玩家、世界和坐标。
- 物品是否被直接删除。

3. 未安装 Audit 时
- 不会创建数据库线程。
- 不会执行不必要的个人垃圾桶身份哈希计算。
- 不影响主插件正常使用。


五、问题修复

1. 修复扫地 guards 不满足时可能重复发送跳过提示的问题。

2. 修复修改 personal-trash.gui.title 后执行 /wtc reload，已经创建过的个人垃圾桶仍显示旧标题的问题。
- 下次打开时会使用新标题。
- 原有垃圾桶物品不会丢失。

3. 修复现代 Paper 上公共垃圾桶 model-id 无效的问题。

4. 修正 model-id 的低版本兼容边界。
- 1.12.2 和 1.13 不再读取无意义的配置字段。
- 1.14+ 才启用 CustomModelData。

5. 补充不同版本配置文件中的中文注释和功能说明。


六、更新总结

本轮更新将公共垃圾桶从固定箱子式实现升级为独立存储系统，增加了双显示模式、玩家独立排序、稳定分页、容量溢出保护、自定义按钮、跨版本光效和 CustomModelData 支持。

扫地系统同时增加了世界过滤、自定义数据识别、精确物品路由和公共垃圾桶准入控制。

此外，插件补齐了审计追踪能力，并修复了个人垃圾桶标题重载、重复 guards 提示和现代版本 model-id 无效等问题。

7.0.0版本之后，所有配置都将发生重大变化。不过，不用担心，因为新插件会自动迁移旧插件的配置。你只需安装新插件即可

WorldListTrashCan 保留旧版的世界垃圾桶、公共垃圾桶、个人垃圾桶、物品黑名单、实体清理、密集实体清理、防丢弃和清理提示，同时重点解决旧版配置混乱、Folia 卡顿、区块强加载、物品误删和跨版本使用不一致的问题。

### 服主最关心的变化

#### 真正新增的功能

| 功能 | 旧版本 | 重构版 |
| --- | --- | --- |
| 公共垃圾桶布局 | 固定布局 | 可配置 1-6 行内容区、翻页按钮、背景和展示物品 |
| 公共垃圾桶按钮 | 材质和位置固定 | 支持材质候选、CustomModelData、名称、Lore 和替代物品 |
| 公共垃圾桶缩容 | 缩小容量可能造成旧物品无处显示 | 自动进入只读溢出页，可查看和取出，不静默丢失 |
| 公共垃圾桶动作 | 只能使用固定按钮 | 支持 `[console]`、`[command]`、`[message]` 和 PAPI 变量 |
| 个人垃圾桶提示 | 单个或批量提示不完整 | 单个物品单独提示，扫地批量汇总提示，默认显示前 3 类 |
| 扫地启动条件 | 到时间就执行 | 可按在线人数和实体数量跳过低压力清理 |
| 手动扫地 | 只有固定执行方式 | `/wtc clear true/false` 可选择是否忽略扫地门禁 |
| 清理状态 | 主要依赖倒计时变量 | `/wtc stats` 直接查看回收、删除、实体、库存和剩余时间 |
| 控制台明细 | 主要显示总数 | 显示前 10 类实体名称、类型、实际数量和其他数量 |
| 实体保护 | 保护项有限 | 支持鞍保护和 Bukkit `Tameable` 主人保护，并排除误判的 shooter/source/掉落者 |
| 按世界直接删除 | 没有独立配置 | 可指定世界，垃圾不进任何垃圾桶，直接删除 |
| 移动物品保护 | 没有 | 可选择扫地时跳过仍在移动的掉落物，默认关闭 |
| 潜影盒物品保护 | 没有 | 可选择跳过掉落物携带的装满潜影盒物品，默认关闭 |

上表只列服主能直接感知的业务变化，没有把内部实现细节重复算成新功能。

#### 兼容性和稳定性增强

- 提供 `WorldListTrashCan-universal.jar`，高低版本和 Folia/Luminol 使用同一个整包；也保留轻量分版本 Jar。
- 1.12.2 到 1.21.x 版本线提供兼容实现；1.16.5+ 支持 RGB，低版本自动降级，也兼容 `&a`、`&c` 等传统颜色码。
- Folia/Luminol 使用区域安全的分段清理任务，不把普通 Bukkit 定时任务直接运行到 Folia 环境。
- 世界垃圾桶默认不强制加载未加载区块，避免清理时突然加载区块造成卡顿。
- 玩家掉落标记放在掉落实体上，不写入物品本身，避免影响物品正常堆叠。
- 旧版配置会被识别并隔离到 `old-version-config`，不直接拿旧配置启动新版逻辑。
- 默认配置缺失项会补回，并且默认配置项带有中文注释。
- bStats 已内置，服主不需要额外开关；插件版本为 `7.0.0`。

### 性能优化估算

以下是根据新旧代码执行路径、默认批量配置和实体数量模型得到的估算，不是 Spark 实测承诺。实际结果会受到加载区块、实体数量、玩家活动和服务器核心影响。

| 场景 | 预计优化 |
| --- | ---: |
| 1000 个加载区块的密集实体周期检查 | 约减少 `96%` 的检查压力 |
| 4096 个加载区块的密集实体周期检查 | 约减少 `96.6%` 的检查压力 |
| 5000 个实体、每秒生成 20 只受限实体的生成路径 | 约减少 `99.98%` 的重复遍历压力 |
| 无玩家在线的自动扫地 | 直接跳过，相关本轮压力接近减少 `100%` |
| 世界垃圾桶位于未加载区块 | 插件主动强加载减少 `100%`，默认改为跳过并降级路由 |
| Folia 4096 区块单轮派发峰值 | 理论瞬时派发峰值约减少 `98.4%` |

#### 综合估算

- 只使用普通定时扫地的服务器：相关路径通常优化约 `0%-30%`。
- 开启密集实体限制的大型服务器：相关主线程压力预计优化约 `80%-99%`。
- 旧版主要卡在世界垃圾桶同步加载区块时：单次清理卡顿峰值预计优化 `90%+`。
- 重构版会增加有限的实体索引和候选队列，预计额外内存约 `5-10MB`，并设置数量上限控制内存增长。

这里的百分比是“对应场景的预计减少”，不是插件整体固定减少百分比。要得到某个服务器的真实数字，应使用 Spark 或服务器自身监控，在相同地图、玩家数和实体数量下分别测试旧版与重构版。

### 推荐配置

重构版的新增保护默认不会改变旧用户行为：

```yaml
# cleanup.yml
guards:
# 在线玩家少于该值时跳过自动扫地。
min-online-players: 1
# 目标实体少于该值时跳过自动扫地。
min-total-entities: 150

# 默认关闭，开启后扫地跳过仍在移动的掉落物。
moving-items:
enabled: false
minimum-speed: 0.01

# 默认关闭，开启后扫地跳过掉落物携带的装满潜影盒物品。
filled-shulker-boxes:
enabled: false
```

“潜影盒物品”指掉落物实体携带的 `ItemStack`，不是世界中已经放置的潜影盒方块。开启后，装有物品的潜影盒掉落物会保留在地面；空潜影盒仍会正常清理。

### 常用命令

```text
/wtc help 查看帮助
/wtc reload 重载配置
/wtc stats 查看最近一次清理状态
/wtc clear true 手动清理并忽略扫地门禁
/wtc clear false 手动清理但遵守扫地门禁
```

正式长命令为 `/worldlisttrashcan`，简写为 `/wtc`。权限统一使用 `WorldListTrashCan.*`。

1.在插件重载时，将关闭玩家已经打开的公共垃圾桶页面。
2.现在，当实体不是怪物且为活体时，认为它是动物。

wtc 更新：
1.清理实体时的“黑名单实体和白名单实体配置” “支持模糊匹配”
2.修复在 “folia” 服务器中使用指令"/wtc clear"之后显示的清理数量不匹配问题
3.重构了部分逻辑

更新日志并不是很及时（群内有第一消息）
1. 修复bossbar发包过大的问题
2. 增加插件配置节点：配置公共垃圾桶的"下一页","上一页","背景板" 的材质和modelId（仅1.16.5以上可用）
3. 更全的垃圾桶记录：增加个人垃圾桶的取出和放入等日志，以及每次扫地具体时间和物品数量的日志
4.更多的权限控制：
WorldListTrashCan.GlobalTrashTakeItem:
description: 玩家使用公共垃圾桶（从公共垃圾桶中取出物品）
default: true
WorldListTrashCan.GlobalTrashPutItem:
description: 玩家使用公共垃圾桶（从公共垃圾桶中放入物品）
default: true
WorldListTrashCan.PersonalTrashTakeItem:
description: 玩家使用个人垃圾桶（从个人垃圾桶中取出物品）
default: true
WorldListTrashCan.PersonalTrashPutItem:
description: 玩家使用个人垃圾桶（从个人垃圾桶中放入物品）
default: true
5.弃用：AllowPutItemInGlobalTrash配置节点，已设置的不影响

#玩家从公共垃圾桶中拿出物品时的间隔（拿取CD,单位毫秒）
#设为0则无视间隔，2000（即2秒） 500 （即0.5秒）
Delay: 500
#是否允许玩家将背包物品放入公共垃圾桶
#默认false
AllowPutItemInGlobalTrash: false
#在每N次扫地时，先清理公共垃圾桶内原有物品，后再将物品加入公共垃圾桶
#如果下面的数是3，则在三次扫地之后，自动清理公共垃圾桶
#如果为-1，则不会清理公共垃圾桶

在“chat” 提示下的最后一句。玩家点击之后可以执行指令（默认是“/wtc globaltrash”）

1.公共垃圾桶目前改为只能取不能放，鼠标单击则取出
2.公共垃圾桶加入日志功能，异步的日志格式 时间，玩家，物品材质，物品名，物品lore，物品附魔

开关在这：

，默认开
日志在插件文件夹下的logs文件夹中，

1.修复开启“NoWorldTrashCanEnterPersonalTrashCan”功能后，丢弃后的物品无法叠加的bug
2.优化"/wtc look "指令查看的区块中的实体列表信息显示
3.支持在清理时的任意时间执行指令列表。例如：在最后一秒执行 "mm mobs killall"

支持西班牙语 (@感谢那位来自西班牙的朋友)

Thank you to this friend from Spain for providing the translation. The plugin now supports Spanish

Gracias a este amigo de España por su traducción, el plug - in ahora admite el español