Jtrash

Jtrash — 世界物品清扫器

Jtrash 是一款 Hytale 服务端插件，能以可配置的时间间隔自动收集所有已加载世界中的掉落物品，将其存入持久化日志，并允许管理员通过可滚动的自定义 UI 面板浏览、恢复或丢弃这些物品。

不再因为成千上万个物品实体堆积在地面上而导致卡顿。不再有“我的物品去哪了？”的疑问——只要清扫器捡起了它，管理员就能在几秒钟内将其归还。

---

功能特性

自动清扫器

• 以完全可配置的时间间隔运行（默认：每 5 分钟）。
• 同时扫描所有已加载世界，每个世界在各自的世界线程上运行——安全、无阻塞。
• 同一清扫周期内掉落的可堆叠物品（相同类型和元数据）会被合并为一个槽位，保持存储整洁易读。
• 耐久物品（工具、武器）会单独存储，并完整保留其精确的耐久度数值。

持久化存储

• 每次清扫后，所有收集到的物品会立即保存到 mods/Jtrash/data/trash.json。
• 可配置的最大物品上限（默认：450 个槽位）。达到上限时，最旧的条目会被自动驱逐（先进先出）。
• 存储数据在服务器重启后依然保留。

管理员 UI 面板（/trash menu）

• 可滚动的 50 行 × 9 列网格 展示每个收集到的物品及其数量和提示信息。
• 一个只读的 5×9 物品栏面板（仓库 + 快捷栏）并排显示管理员当前持有的物品。
• 点击垃圾网格中的任意槽位即可将该物品立即恢复到管理员的物品栏中——耐久度完全保留。
  • 如果物品栏已满，物品将留在垃圾中并发送提示消息。
  • 部分恢复（物品栏在一组物品中途填满）会被妥善处理——剩余部分留在垃圾中。
• 清空垃圾按钮可一键清除整个存储。
• 所有面板标签和按钮文本均根据服务器配置的语言完全本地化。

广播系统

• 在每次清扫前 1 分钟 和 30 秒 警告所有在线玩家——聊天消息 + 全屏覆盖标题。
• 清扫完成后广播收集到的物品总数。
• 每种广播类型都可以在 config.json 中独立开关：
  • broadcastWarningEnabled — 控制清扫前警告。
  • broadcastCompletedEnabled — 控制清扫后总结。

国际化（i18n）

• 内置 3 种语言：en_US、pt_BR、es_ES。
• 任何缺失的翻译键会自动回退到 en_US——插件绝不会因翻译文件不完整而崩溃。
• 所有消息文件都安装在 mods/Jtrash/Messages/ 目录下，可完全编辑。
• 插件更新中新增的键会自动合并——现有自定义内容永远不会被覆盖。

命令别名

• 服务器所有者可以直接在 config.json 中为主要的 /trash 命令定义自定义别名（例如 /lx、/garbage、/lixo）。
• 别名会在启动时与主命令一同注册——无需额外设置。

热重载

• /trash reload 可重新加载 config.json 和所有消息文件，并以新的时间间隔重启清扫器——无需重启服务器。
• JSON 合并会在每次重载时自动执行，将任何新的配置键修补到现有文件中。

---

命令

命令	描述	权限
/trash menu	打开管理员 UI 面板	jtrash.admin
/trash reload	重新加载配置和消息	jtrash.admin

---

配置

所有选项都位于 mods/Jtrash/config.json 中，首次启动时自动创建。

{
  "intervalMinutes": 5,
  "maxItems": 450,
  "language": "en_US",
  "broadcastWarningEnabled": true,
  "broadcastCompletedEnabled": true,
  "commandAliases": []
}

字段	类型	默认值	描述
intervalMinutes	整数	5	清扫周期之间的间隔分钟数。必须 > 0。
maxItems	整数	450	存储的最大槽位数。满时最旧条目先被驱逐。
language	字符串	"en_US"	主要语言代码。缺失的键会回退到 en_US。
broadcastWarningEnabled	布尔值	true	如果为 false，则抑制 -60 秒和 -30 秒的清扫前警告。
broadcastCompletedEnabled	布尔值	true	如果为 false，则抑制清扫后的物品数量广播。
commandAliases	字符串数组	[]	/trash 的额外别名。示例：["lx", "lixo", "garbage"]。下次服务器启动时生效。

---

权限

权限	描述
jtrash.admin	授予访问 /trash menu 和 /trash reload 的权限。

---

文件结构

首次启动后，Jtrash 会在服务器模组数据目录内创建以下布局：

mods/
└── Jtrash/
    ├── config.json          ← 主配置
    ├── data/
    │   └── trash.json       ← 持久化物品存储
    └── Messages/
        ├── en_US.json
        ├── pt_BR.json
        └── es_ES.json

---

工作原理

1. 清扫器守护进程每 intervalMinutes 分钟调度一次清扫。
2. 清扫前，向所有玩家广播警告（如果启用）。
3. 清扫时，每个世界线程通过 ECS 遍历其物品实体。同一周期内收集的可堆叠物品会在持久化之前合并。
4. 收集到的物品实体从世界中移除，其数据保存到 trash.json。
5. 清扫后，发送包含总收集数的完成广播（如果启用）。
6. 管理员运行 /trash menu 打开面板，浏览收集到的物品，并根据需要恢复或清除物品。

---

要求

• Hytale 服务器（任何版本——"ServerVersion": "*"）
• 无强制依赖

---

可选依赖

插件	用途
Jvips	VIP 等级系统——适合基于角色的服务器管理搭配使用。
Jbank	经济/股票交易系统——属于同一 JPlugins 套件。

---

属于 JPlugins 套件，由 julio 开发。