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.