Serversentials

A high-performance, network-compatible, and Folia-ready utility suite designed to replace legacy essentials plugins on modern Minecraft servers and proxy networks.

---

Overview

Essentials suites often struggle when deployed on multi-threaded Folia environments or synchronized across proxy networks.

Serversentials is built from the ground up to address these platform limitations. It operates as a unified, high-performance hybrid JAR capable of running on backend servers (Paper, Folia) and proxy servers (Velocity) simultaneously.

Architecture Highlights

• Folia Optimization: Asynchronous execution and global/region-specific task scheduling to ensure complete compatibility with Folia's multi-threaded region model.
• Hybrid JAR Architecture: The same plugin file is loaded on both the backend game servers and your Velocity proxy.
• Dual-Dialect Storage: High-performance database operations powered by HikariCP, supporting local SQLite file storage or network-synchronized MySQL databases.
• Automatic Configuration Migrator: Upgrades configuration files seamlessly on plugin updates while preserving custom values, formatting, and inline comments.

---

Feature Breakdown

Network Teleportation & Movement

• Cross-Server Teleportation: Send request-based /tpa and /tpahere teleports across different servers on your proxy network. Includes administrative bypass commands (/tpo and /tpohere).
• Session Tracking: Hop back to your previous location or death coordinate across servers using /back.
• Utility Teleports: Teleport to safe random coordinates within world borders using /rtp, or jump to the highest block above your coordinates with /top.
• Warps & Homes: Set multi-home profiles (permission-capped) and global warps with support for custom warmups and cooldown timers.

Chat & Messaging

• Cross-Server Whispering: Perform private messaging network-wide using /msg and /reply with built-in /socialspy for administration.
• Staff Communication: Staff-only channel using /staffchat to coordinate privately across the network.
• Modern Chat Renderer: Fully custom chat formatting engine with MiniMessage syntax support, integrated with Vault/LuckPerms prefixes, suffixes, and display names.
• Connection Events: Custom join and leave messages featuring PlaceholderAPI support, configurable to be toggled on or off independently.

Extra Inventories (/inv)

• Multi-Profile Inventories: Allows players to unlock and switch between up to 11 individual inventory profiles (1 base profile + 10 extra slots).
• Interactive GUI: Preview profiles in a custom 54-slot chest interface displaying armor, offhand items, and player details.
• Administrative Management: View or clear player inventories on demand using /inv view and /inv clear.
• Revocation Safety: If a player loses permission for an inventory, it is set to "Locked" status, allowing them to extract their items safely but preventing new item storage.
• Custom NBT Support: Safely serializes complex custom NBT data, making it fully compatible with custom item plugins like Nexo.

Economy

• Network Transactions: Send currency to players on the same server or across the proxy network with /pay.
• Vault Integration: Fully hooks into Vault to act as a robust server economy provider.
• Leaderboards: Display top currency holder statistics with /baltop.

Moderation & Administration

• Live Perspective Monitoring: The /monitor command allows administrators to enter spectator mode to monitor a player's perspective (locally or cross-server) and return safely to their original server, coordinates, and gamemode upon exit.
• Vanish Integration: Hides vanished players from join queries and integrates with TAB/TAB-bridge to automatically remove vanished players from the global tablist.
• Suggestion Sanitization: Dynamically filters command tab-completion suggestions so players only see commands they have permission to execute.

---

Installation Guide

Single Server Setup

1. Download the Serversentials.jar file.
2. Place the jar file inside your server's plugins/ directory.
3. Start the server to generate the default configuration files.

Proxy Network Setup (Velocity + Backend Servers)

1. Place the Serversentials.jar file inside your Velocity proxy's plugins/ folder.
2. Place the same Serversentials.jar file inside the plugins/ folder of all backend Paper/Folia servers.
3. Start the proxy and backend servers to generate the default configuration files.
4. On each backend server, edit plugins/Serversentials/config.yml and set the server-name key to match exactly the server's registered name in your Velocity velocity.toml configuration (e.g. lobby, survival-1).
5. Restart the backend servers to initialize network synchronization.

---

Commands & Permissions Reference

1. Teleportation & Movement

Command & Arguments	Aliases	Description	Permission Node
/tpa <player>	-	Request to teleport to a player	serversentials.tpa
/tpahere <player>	tpah	Request a player teleport to you	serversentials.tpahere
/tpaccept	tpc	Accept a pending teleport request	serversentials.tpaccept
/tpdeny	tpd	Deny a pending teleport request	serversentials.tpdeny
/tptoggle	tpt	Toggle incoming teleport requests	serversentials.tptoggle
/tpo <player>	-	Force teleport to a player (admin bypass)	serversentials.tpo
/tpohere <player>	-	Force teleport a player to you (admin bypass)	serversentials.tpohere
/back	-	Return to previous position or death point	serversentials.back
/rtp	-	Teleport to a random safe location	serversentials.teleport.rtp
/top	-	Teleport to the highest block above you	serversentials.teleport.top

2. Messaging & Communication

Command & Arguments	Aliases	Description	Permission Node
/msg <player> <message>	w, tell, pm, message	Send a private message (cross-server)	serversentials.msg
/r <message>	reply	Reply to the last received private message	serversentials.reply
/socialspy	-	Toggle spying on private messages	serversentials.socialspy
/sc <message>	staffchat	Broadcast a message to the staff channel	serversentials.staffchat

3. Extra Inventories

Command & Arguments	Aliases	Description	Permission Node
/inv list	inventory	Open the extra inventory selection GUI	serversentials.extrainv
/inv <1-11>	inventory	Quick-switch to a specific inventory slot	serversentials.extrainv
/inv view <player> [slot]	inventory	View a player's extra inventory (admin)	serversentials.extrainv.admin
/inv clear <player> [slot]	inventory	Clear a player's extra inventory (admin)	serversentials.extrainv.admin

4. Player Customization & Economy

Command & Arguments	Aliases	Description	Permission Node
/nick <name>	-	Set a custom display name / nickname	serversentials.nick
/nick off	-	Clear your active nickname	serversentials.nick
/whois <nickname>	-	Reveal the real username behind a nickname	serversentials.whois
/balance [player]	bal	Check a player's current account balance	serversentials.balance
/pay <player> <amount>	-	Transfer funds to another player	serversentials.pay
/economy <give|set|deduct> <player> <amount>	eco	Modify player balances (admin)	serversentials.economy
/baltop [page]	-	Display top server balances	serversentials.baltop

5. Moderation & Server Administration

Command & Arguments	Aliases	Description	Permission Node
/monitor <player>	mon	Start spectating a player's perspective	serversentials.monitor
/monitor	mon	Stop spectating and return to original state	serversentials.monitor
/vanish [player]	v	Toggle invisibility / vanish status	serversentials.vanish
/invsee <player>	-	View or modify a player's inventory	serversentials.invsee
/heal [player]	-	Restore player health	serversentials.heal
/feed [player]	-	Restore hunger bars	serversentials.feed
/god [player]	-	Toggle invulnerability state	serversentials.god
/ssreload	-	Reload configuration files	serversentials.reload

6. Homes & Warps

Command & Arguments	Aliases	Description	Permission Node
/home [name]	-	Teleport to a set home coordinate	serversentials.home
/sethome [name]	-	Create a home point at your location	serversentials.sethome
/delhome <name>	-	Delete an existing home point	serversentials.delhome
/homes [player]	-	List your homes or another player's homes	serversentials.homes
/warp <name>	-	Teleport to a public warp location	serversentials.warp
/setwarp <name>	-	Set a public warp location	serversentials.setwarp
/delwarp <name>	-	Remove a public warp location	serversentials.delwarp
/warps	-	List all available warp points	serversentials.warps

7. Utility GUIs & Item Editors

Command & Arguments	Aliases	Description	Permission Node
/craft	-	Open a portable crafting bench GUI	serversentials.craft
/echest [player]	ec	Open a player's virtual ender chest	serversentials.echest
/anvil	-	Open a portable anvil GUI	serversentials.anvil
/loom	-	Open a portable loom GUI	serversentials.loom
/stonecutter	scutter	Open a portable stonecutter GUI	serversentials.stonecutter
/smithingtable	smith	Open a portable smithing table GUI	serversentials.smithingtable
/item <material> [amount]	i	Spawn a specified item (admin)	serversentials.item
/itemrename <name>	iname, itemname	Rename the display name of your held item	serversentials.itemrename
/lore <add|set|insert|delete|clear> [index] [text]	-	Modify item lore lines	serversentials.lore
/enchant <enchantment> [level] [player]	ench	Apply custom enchants to the held item	serversentials.enchant

8. World & Environment

Command & Arguments	Aliases	Description	Permission Node
/day	-	Set the local world time to day	serversentials.worldcommands
/noon	-	Set the local world time to noon	serversentials.worldcommands
/night	-	Set the local world time to night	serversentials.worldcommands
/clear	sun	Change local weather to clear	serversentials.worldcommands
/rain	-	Change local weather to rain	serversentials.worldcommands
/storm	-	Change local weather to storm	serversentials.worldcommands

---

PlaceholderAPI Integration

Requires PlaceholderAPI. If using Folia, use a Folia-compatible fork.

Placeholder	Description	Example Output
%serversentials_name%	The player's vanilla username	Jolly
%serversentials_displayname%	The formatted nickname (falls back to username) resolved to legacy section codes	&c[Admin] &eJolly
%serversentials_nickname%	The active nickname (falls back to username) resolved to legacy section codes	&eJollyJoe
%serversentials_nickname_raw%	The raw MiniMessage nickname string stored in the database	<gold>JollyJoe
%serversentials_has_nickname%	Returns true if the player has an active nickname set, otherwise false	true
%serversentials_isflying%	Returns true if the player is currently flying, otherwise false	false
%serversentials_gamemode%	The player's current game mode	SURVIVAL
%serversentials_ping%	The player's current ping	24
%serversentials_vanished%	Returns true if the player is vanished, otherwise false	false
%serversentials_hidden%	Returns true if the player is hidden from others, otherwise false	false
%serversentials_godmode%	Returns true if the player is in god mode, otherwise false	false
%serversentials_teleport_toggle%	Returns true if the player accepts teleport requests, otherwise false	true
%serversentials_active_inventory_slot%	The current active inventory slot number (1-11) for the player	2
%serversentials_inventory_max_slots%	The total number of inventory slots (1-11) the player has permission for	5
%serversentials_fly_speed%	The player's flight speed multiplier (0-10)	2.0
%serversentials_walk_speed%	The player's walking speed multiplier (0-10)	2.0
%serversentials_eco_balance%	The player's raw economy balance	542.50
%serversentials_eco_balance_formatted%	The player's formatted economy balance	$542.50

---

Configuration

server-name: "default"
# If using on a velocity network, change this to the configured server name for this server as it is in your velocity.toml file
# If running a single server, no need to change this
# Set this properly if on a proxy network to avoid issues with teleporting!!!

database:
  type: sqlite # or "mysql" use sqlite if you haven't set up a mysql server
  # SQLite options
  file: serversentials.db
  # MySQL options (used only if type = mysql)
  host: localhost
  port: 3306
  database: serversentials
  username: root
  password: ""
  useSSL: false
  pool-size: 10

modules:
  # serversentials.home <- /home and /sethome
  # serversentials.sethome.<#> <- Number of homes
  # serversentials.home.cooldown.<#> <- Cooldown per /home command
  # servesentials.home.countdown.<#> <- Countdown before teleporting
  home: true
  nick: # serversentials.nick
    enabled: true
    maxlength: 32 # This includes MiniMessage formatting <red>JollyJoe <- counts 13
  #---------TELEPORTS----------
  tpa: #serversentials.tpa
    enabled: true
    expiration: 20 # Seconds before teleport requests expire
  tpahere: # serversentials.tpahere
    enabled: true
    expiration: 20 # Seconds before teleport requests expire
  tptoggle: true # serversentials.tptoggle <- Toggles teleport requests on/off
  tpo: true # serversentials.tpo <- Tpa override
  tpohere: true # serversentials.tpohere <- Tpahere override

  # serversentials.warp <- /warp
  # serversentials.warp.<warpname> <- /warp <name>
  # serversentials.setwarp <- /setwarp
  # serversentials.warp.cooldown.<#>
  # serversentials.warp.countdown.<#>
  warp: true
  teleport:
    top: true
    rtp: true #I recommend using my RTP plugin for more configuration!
    back: true
    # https://modrinth.com/plugin/rtp-gui (if you DO install this, set rtp: false)
  #---------UTILITIES----------
  craft: true # serversentials.craft
  anvil: true # serversentials.anvil
  loom: true # serversentials.loom
  echest: true # serversentials.echest
  stonecutter: true # serversentials.stonecutter
  smithingtable: true # serversentials.smithingtable
  #---------MODERATION-----------
  invsee: true # serversentials.invsee
  vanish: true # serversentials.vanish || serversentials.vanish.see || serversentials.vanish.others
  gamemode: true # serversentials.gms/gmc/gmsp || serversentials.gms/gmc/gmsp.others
  fly: true # serversentials.fly || serversentials.fly.others
  flyspeed: true # serversentials.flyspeed || serversentials.flyspeed.others
  walkspeed: true # serversentials.walkspeed || serversentials.walkspeed.others
  monitor: true # serversentials.monitor
  extra-inventories: true # serversentials.extrainv || serversentials.extrainv.amount.<1-10> || serversentials.extrainv.admin
  #---------EXTRAS----------
  heal: true # serversentials.heal || serversentials.heal.others
  feed: true # serversentials.feed || serversentials.feed.others
  god: true # serversentials.god || serversentials.god.others
  item: # serversentials.item || serversentials.item.others <- /item command
    enabled: true
    respect-max-stack-size: true # true = don't allow oversized stacks
  enchant:
    respect-max-levels: true # true = don't allow over-limit enchants
  worldcommands: true #/day, /night, /noon, /clear, /rain, /storm
  #---------ECONOMY-------
  economy:
    enabled: true
    starting-balance: 100.0
    currency-symbol: "$"
    formatted: true # true = show commas and decimals, false = plain numbers
    decimals: 2 # number of decimal places
    cross-server-pay: true # Enable sending money to players on other servers on the network
  #---------CHAT FORMATTING---------
  chat:
    enabled: true
    cross-server-chat: false # Enable to relay chat messages across all servers on the network
    # Chat format — supports PlaceholderAPI placeholders and built-in: {server}, {player}, {prefix}, {suffix}, {message}
    # {player} uses display names (respects /nick)
    # Example with LuckPerms: "%luckperms_prefix%{player} <dark_gray>»</dark_gray> {message}"
    chat-format: "<dark_gray>[<aqua>{server}</aqua>]</dark_gray> <gray>{prefix}</gray><white>{player}</white><gray> » {message}</gray>"
    # Join/Leave messages — supports PlaceholderAPI placeholders and {player}
    # Set enabled to false to hide the message entirely
    join-message:
      enabled: true
      format: "<green>+ <yellow>{player} <gray>joined the server"
    leave-message:
      enabled: true
      format: "<red>- <yellow>{player} <gray>left the server"

messages:
  no-permission: "<red>You do not have permission to use this command!</red>"
  player-not-found: "<red>Player not found!</red>"
  starting-balance: "<green>You received your starting balance of {symbol}{amount}!</green>"
  balance-display: "<green>{player}'s balance: <yellow>{symbol}{balance}</yellow>"
  pay-usage: "<red>Usage: /pay <player> <amount>"
  pay-insufficient: "<red>You do not have enough funds!"
  pay-sent: "<green>You sent {symbol}{amount} to {player}."
  pay-received: "<green>You received {symbol}{amount} from {player}."
  economy-usage: "<red>Usage: /economy <give/set/deduct> <player> <amount>"
  economy-success: "<green>{action} {symbol}{amount} for {player}."
  baltop-header: "<gold>--- Top balances - Page: {page} ----"
  baltop-line: "<yellow>{rank}. {player} - {symbol}{balance}"
  baltop-empty: "<red>No balances found!"
  invalid-number: "<red>Invalid number!"
  invalid-recipient: "<red>You cannot send money to yourself!"

---

Dependencies

• Vault (or any compatible economy/chat provider plugin)

---

Development & Support

Serversentials is actively maintained by a solo developer. For support, bug reports, and suggestions, please join the official Discord server.