Jtrash — World Item Sweeper

Jtrash is a server-side plugin for Hytale that automatically collects dropped items from all loaded worlds at a configurable interval, stores them in a persistent log, and lets administrators browse, restore, or discard them through a scrollable Custom UI panel.

No more lag from thousands of item entities piling up on the ground. No more "where did my item go?" — if the sweeper grabbed it, admins can hand it back in seconds.

Features

Automatic Sweeper

Runs on a fully configurable interval (default: every 5 minutes).
Scans all loaded worlds simultaneously, each on its own world thread — safe, non-blocking.
Stackable items (same type and metadata) dropped before the same sweep cycle are merged into a single slot, keeping the storage clean and readable.
Durable items (tools, weapons) are stored individually with their exact durability values preserved.

Persistent Storage

All collected items are saved to mods/Jtrash/data/trash.json immediately after each sweep.
Configurable max item cap (default: 450 slots). When the cap is reached, the oldest entries are evicted automatically (FIFO).
Storage survives server restarts.

Admin UI Panel (`/trash menu`)

A scrollable 50-row × 9-column grid displays every collected item with its quantity and tooltip.
A read-only 5×9 inventory panel (Storage + Hotbar) shows the admin's current items side by side.
Click any slot in the trash grid to instantly restore that item to the admin's inventory — durability is fully preserved.
- If the inventory is full, the item stays in the trash and a message is sent.
- Partial restores (inventory fills mid-stack) are handled gracefully — the remainder stays in trash.
Clear Trash button wipes the entire storage with a single click.
All panel labels and button text are fully localized based on the server's configured language.

Broadcast System

Warns all online players 1 minute and 30 seconds before each sweep — chat message + fullscreen overlay title.
Broadcasts the total item count collected after the sweep completes.
Each broadcast type can be toggled independently in config.json:
- broadcastWarningEnabled — controls the pre-sweep warnings.
- broadcastCompletedEnabled — controls the post-sweep summary.

Internationalization (i18n)

Ships with 3 built-in languages: en_US, pt_BR, es_ES.
Automatic fallback to en_US for any missing translation key — the plugin never breaks due to an incomplete translation file.
All message files are installed in mods/Jtrash/Messages/ and are fully editable.
New keys added in plugin updates are merged automatically — existing customizations are never overwritten.

Command Aliases

Server owners can define custom aliases for the main /trash command (e.g. /lx, /garbage, /lixo) directly in config.json.
Aliases are registered on startup alongside the main command — no extra setup required.

Hot Reload

/trash reload reloads config.json and all message files and restarts the sweeper with the new interval — no server restart needed.
The JSON merge runs automatically on every reload, patching any new config keys into existing files.

Commands

Command	Description	Permission
`/trash menu`	Opens the admin UI panel	`jtrash.admin`
`/trash reload`	Reloads config and messages	`jtrash.admin`

Configuration

All options live in mods/Jtrash/config.json, created automatically on first boot.

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

Field	Type	Default	Description
`intervalMinutes`	integer	`5`	Minutes between sweep cycles. Must be > 0.
`maxItems`	integer	`450`	Maximum slots stored. Oldest entries evicted first when full.
`language`	string	`"en_US"`	Primary language code. Falls back to `en_US` for missing keys.
`broadcastWarningEnabled`	boolean	`true`	If `false`, suppresses the -60s and -30s pre-sweep warnings.
`broadcastCompletedEnabled`	boolean	`true`	If `false`, suppresses the post-sweep item count broadcast.
`commandAliases`	string array	`[]`	Extra aliases for `/trash`. Example: `["lx", "lixo", "garbage"]`. Takes effect on next server start.

Permissions

Permission	Description
`jtrash.admin`	Grants access to `/trash menu` and `/trash reload`.

File Structure

After the first boot, Jtrash creates the following layout inside the server's mod data directory:

mods/
└── Jtrash/
    ├── config.json          ← main configuration
    ├── data/
    │   └── trash.json       ← persistent item storage
    └── Messages/
        ├── en_US.json
        ├── pt_BR.json
        └── es_ES.json

How It Works

The sweeper daemon schedules a sweep every intervalMinutes.
Before the sweep, it broadcasts warnings to all players (if enabled).
At sweep time, every world thread iterates its item entities via the ECS. Stackable items collected in the same cycle are merged before persisting.
Collected item entities are removed from the world and their data is saved to trash.json.
After the sweep, a completion broadcast is sent with the total collected count (if enabled).
An admin runs /trash menu to open the panel, browse what was collected, and restore or clear items as needed.

Requirements

Hytale Server (any version — "ServerVersion": "*")
No mandatory dependencies

Optional Dependencies

Plugin	Purpose
Jvips	VIP rank system — pairs well for role-based server management.
Jbank	Economy / stock exchange — part of the same JPlugins suite.

Part of the JPlugins suite by julio.