xUtilities

A lightweight, high-performance utility-command plugin for Paper (and Folia) networks. xUtilities is meant to be installed on every server — lobby, survival, minigame, anything — providing the small, essential quality-of-life commands virtually every server needs regardless of type: gamemode switches, flight, speed, teleport-to-top, virtual workstation menus, heal/feed, inventory tools, and fully-custom info/link commands.

Because it runs everywhere, it adds near-zero overhead: no always-on tick work, a tiny memory footprint, and clean, fail-safe startup/reload. Every command is individually toggleable, permissioned, aliasable, and has fully customizable MiniMessage text — so each server enables exactly the subset it wants.

xUtilities is built to stay up: every code path fails safe. It never throws out of enable/reload, never blocks the main thread, and never disables itself on a bad config value.

---

✨ Features

• Gamemode — /survival /creative /adventure /spectator, plus the /gamemode <mode> [player] parent that wires in whichever modes are enabled. Self or another player (with .others).
• Player utility — /fly (toggle flight), /speed (1–10 fly/walk speed), /top (async-teleport to the highest safe block), /setrotation (yaw/pitch), /ping (latency), /back (return to your previous location / death spot).
• State & inventory — /heal (health, optionally hunger, fire, negative effects), /feed, /repair (held item, or /repair all), /clear, /enderchest.
• Virtual workstation menus — /anvil, /craft, /grinder, /loom, /smith, and /trash (a disposal inventory discarded on close). Open the vanilla UI without a placed block.
• Data-driven info/link commands — owner-defined clickable links; ships editable /discord, /store, /website defaults and lets you add arbitrary ones (e.g. /vote) with zero code.
• /xutilities reload / /xutilities info — reload re-reads and re-validates config and re-applies all message/behaviour values live; info shows build/version + status.
• Fully configurable — per-command enabled, aliases, permission(s) and MiniMessage text, plus a shared messages.error.* block. Safe defaults on; bad values fall back with a warning.
• Folia-ready — every player mutation runs on the correct region thread; /top and /back use async teleport; no entity is touched off its region thread. One jar, correct on Paper, Purpur and Folia.

---

📦 Requirements

• Paper 1.20.6+ (or a fork like Purpur, or Folia)
• Java 21 runtime

---

🚀 Install

1. Grab a jar (see Downloads below) and drop it in your server's plugins/ folder.
2. Start the server once — xUtilities writes a default config.yml.
3. Edit plugins/xUtilities/config.yml to taste, then run /xutilities reload. Messages and behaviour values apply live; enabling/disabling a command, changing its aliases or permissions, and adding/removing/renaming info-commands are restart-only (they apply when commands are registered at startup).
4. Grant the xutilities.command.* permissions to your staff ranks as needed (see Commands & permissions).

---

⌨️ Commands & permissions

Self-only commands (and the self form of dual commands) reject console with the configured player-only message; [player] forms may run from console/command blocks. .others is required to act on another player.

Command	Permission	Default	.others permission	Default
/survival /creative /adventure /spectator /gamemode	xutilities.command.<name>	op	….<name>.others	op
/fly	xutilities.command.fly	op	xutilities.command.fly.others	op
/speed	xutilities.command.speed	op	xutilities.command.speed.others	op
/top	xutilities.command.top	op	—	—
/setrotation	xutilities.command.setrotation	op	….setrotation.others	op
/ping	xutilities.command.ping	everyone	xutilities.command.ping.others	op
/back	xutilities.command.back	op	—	—
/heal	xutilities.command.heal	op	xutilities.command.heal.others	op
/feed	xutilities.command.feed	op	xutilities.command.feed.others	op
/repair	xutilities.command.repair	op	xutilities.command.repair.others	op
/clear	xutilities.command.clear	op	xutilities.command.clear.others	op
/enderchest	xutilities.command.enderchest	op	….enderchest.others	op
/anvil /craft /grinder /loom /smith /trash	xutilities.command.<name>	op	—	—
info/link commands	xutilities.command.<name>	everyone	—	—
/xutilities reload / /xutilities info	xutilities.admin	op	—	—

All permissions are declared in paper-plugin.yml with these safe defaults out-of-the-box. Custom permissions set in config that aren't declared default to op-only; set them blank ("") for no restriction.

---

⚙️ Recommended setup

• Permissions. Out of the box only ops can run the staff commands; everyone can run /ping and the info/link commands. Grant the specific xutilities.command.* nodes to your staff ranks in your permissions plugin, and grant the .others node separately where a rank should act on other players.
• Folia. xUtilities declares Folia support and runs every player mutation on the correct region thread (/top and /back use async teleport). No configuration is needed — the same jar runs on Paper, Purpur and Folia.
• Curate your info/link commands. Replace the example URLs in info-commands, delete the ones you don't want, and add server-specific ones (vote, rules, forums, …). Remember these are restart-only.

---

⚡ How it stays fast & lightweight

• No always-on work. xUtilities schedules no repeating tasks. The only event listener exists solely for /back, and it's registered only when /back is enabled — idle cost is effectively zero.
• Immutable settings snapshot. Config is parsed once into an immutable object with all MiniMessage components pre-parsed, and swapped atomically on /xutilities reload. No command path reads getConfig() or re-parses static text; only templates with a per-use placeholder are resolved on their (rare, human-triggered) invocation.
• Register only what's enabled. Command nodes are built only for enabled commands, so disabled features add no command-tree or tab-completion cost.
• Thread-correct + Folia-aware. Player mutations run on the entity's scheduler; teleports use teleportAsync. One jar, correct on Paper and Folia.
• Fail-safe everywhere. onEnable/reload and every command registration are wrapped so a bad value or one broken command is logged and skipped, never taking the server (or the network) down.